Skip to content

About

Track total, daily, weekly, and monthly curseforge release downloads via a GitHub Action with badge-ready JSON and optional SVG charts.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Latest commit

 

History

117 Commits

Folders and files

N6REJ/curseforge-downloads-action

Release License: Apache-2.0 Runtime Node 24 Tests Actionlint CodeQL

Keep track of your CurseForge mod downloads over time and present the results as clean badges or optional charts.

The history stays in your repository, with no separate statistics server to maintain.

Start here (quick install)

Choose one setup template:

Setup Use when Template
Daily badges You want a simple daily download total https://github.com/N6REJ/curseforge-downloads-action/blob/main/templates/workflows/curseforge-daily.yml
More frequent updates You want the current day to refresh more often https://github.com/N6REJ/curseforge-downloads-action/blob/main/templates/workflows/curseforge-hourly.yml
Daily badges and charts You want download numbers and visual trends https://github.com/N6REJ/curseforge-downloads-action/blob/main/templates/workflows/curseforge-daily-with-chart.yml
  1. Download or copy the template that matches the result you want.
  2. Place the file in the repository under .github/workflows/.
  3. Set curseforge_mod_id to the numeric CurseForge mod (project) ID you want to track.
  4. (Optional) Add a repository secret named CF_STUDIO_API_KEY for the official CurseForge for Studios API (Settings → Secrets and variables → Actions → New repository secret). Without it, the action uses the public cfwidget API, which needs no key.
  5. Commit and push.
  6. Open the repository's Actions tab and select Run workflow once.
  7. Add one or both badges to the README, replacing _OWNER_ and _REPOSITORY_:
![Downloads total](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.total&label=downloads%2Ftotal&color=0A7EA4)
![Downloads / day](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.day&label=downloads%2Fday&color=1E8E3E)

Where do I find these values?

  • CurseForge mod id: open your project on CurseForge. The number in the project URL (curseforge.com/minecraft/mc-mods/<slug> → see the project's "Project ID" under the About section) is the curseforge_mod_id.
  • CurseForge API key (optional): create one from your CurseForge for Studios account and store it as the CF_STUDIO_API_KEY secret.

Which download source is used?

The action supports two sources and picks them automatically:

Condition Source Key required Notes
cf_studio_api_key set Official CurseForge for Studios API (api.curseforge.com) Yes Stable and supported; preferred.
cf_studio_api_key unset Public cfwidget API (api.cfwidget.com) No Zero-setup fallback for casual use.
Key set but the official API rejects the request cfwidget fallback n/a The action logs a warning and retries against cfwidget.

Both sources return a single running download total, so day/week/month/year comparisons work the same either way.

The cfwidget fallback is an independent, community-run service. It is convenient and needs no account, but it is not operated by CurseForge. For the most reliable results, set CF_STUDIO_API_KEY.

Public badges need a publicly readable result file. Private repositories usually cannot display them to signed out visitors.

Why this action exists

CurseForge shows your mod's lifetime download count, but it does not show how that total changed over time.

CurseForge Downloads Action keeps that short history for you. On a schedule you choose, it reads the current number from the CurseForge API, saves the total for the day, and updates the small files used by your badges and charts.

Everything remains in the repository, making the result easy to inspect, reuse, and remove without depending on a hosted analytics account.

How it works (short version)

  1. Read the download total for your mod from the CurseForge API using curseforge_mod_id. If the CF_STUDIO_API_KEY secret is set, the official CurseForge for Studios API is used; otherwise the action falls back to the public cfwidget API.
  2. Save one total for the current day.
  3. Compare the available history to show day, ISO week, calendar month, and calendar year changes.
  4. Clearly mark a comparison as partial when there is not yet enough history for the complete calendar period.
  5. Publish the result to stats-data:curseforge/downloads.json by default.
  6. Optionally publish chart images from the same history.

Architecture at a glance

flowchart LR
  A[Scheduled workflow] --> B[curseforge-downloads-action]
  B --> C[CurseForge mod download total]
  C --> B
  B --> D[Daily history and comparisons]
  D --> E[Badge data]
  D --> F[Optional chart images]
  E --> G[README badges]
  F --> H[README charts]
Loading

About the source URL

The badge reads the small public data file produced by the action. With the default settings, its address follows this pattern:

Default source URL pattern:

https://raw.githubusercontent.com/<_OWNER_>/<_REPO_>/stats-data/curseforge/downloads.json

stats-data is simply the branch used to store the generated files. It is a plain data branch and is not tied to any GitHub Pages website.

raw vs jsDelivr:

  • raw.githubusercontent.com is direct and simple, and is used by the examples in this README.
  • cdn.jsdelivr.net can be faster in some locations, although updates may take longer to appear.

Alternative jsDelivr pattern:

https://cdn.jsdelivr.net/gh/<_OWNER_>/<_REPO_>@stats-data/curseforge/downloads.json

Periods (calendar buckets)

day, week, month, and year are calendar periods, not rolling windows:

  • day = the current day (since the previous snapshot).
  • week = the current ISO week (Monday–Sunday, UTC).
  • month = the current calendar month (since the 1st, UTC).
  • year = the current calendar year (since January 1, UTC).

Each value is today's total − the snapshot at the period start. The periods block in the JSON records each period's start, end, and a label (2026-W43, Oct 2026, 2026).

Warm-up period (important)

Calendar comparisons need a snapshot at or after the period start. A new setup therefore takes time to build history, and values reset when a period rolls over.

  • A comparison is complete when a snapshot exists exactly on the period start date.
  • If the exact date is missing but a later snapshot exists, the value is the best available and is flagged partial.
  • If no snapshot is retained at or after the period start, the value is partial.

A partial value is not a failure. It is the best comparison available from the dates collected so far.

Retention: the action keeps enough history for the current calendar year automatically. The effective window_days is raised to at least the day-of-year (up to ~366) so a January 1 baseline is retained even when window_days is smaller.

Because buckets are calendar-based, values reset at period boundaries: month drops to a small number on the 1st, year on January 1, and week each Monday.

README badge examples (copy-paste)

Replace _OWNER_ and _REPOSITORY_.

Total downloads

![Downloads total](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY_%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.total&label=downloads%2Ftotal&color=0A7EA4)

Preview:

Downloads total

Daily downloads

![Downloads day](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY_%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.day&label=downloads%2Fday&color=1E8E3E)

Preview:

Downloads day

Weekly downloads

![Downloads week](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY_%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.week&label=downloads%2Fweek&color=0069C2)

Preview:

Downloads week

Monthly downloads

![Downloads month](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY_%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.month&label=downloads%2Fmonth&color=B26A00)

Preview:

Downloads month

Yearly downloads

![Downloads year](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY_%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.stats.year&label=downloads%2Fyear&color=6A1B9A)

Preview:

Downloads year

Profile mode (daily/hourly) badge

![Downloads profile](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F_OWNER_%2F_REPOSITORY_%2Fstats-data%2Fcurseforge%2Fdownloads.json&query=%24.profile.defaultMode&label=downloads%2Fprofile&color=5E35B1)

Preview:

Downloads profile

Attribution

<sub>Powered by <a href="https://github.com/N6REJ/curseforge-downloads-action">curseforge-downloads-action</a></sub>

Preview:

Powered by curseforge-downloads-action

Charts (optional)

You can publish static SVG charts and embed them directly in your README.

Enable chart publishing in workflow:

with:
  publish_chart: "true"
  chart_output_path: "curseforge/downloads-trend.svg"
  chart_types: "total-trend,daily,weekly,monthly,yearly"
  chart_themes: "black,slate,orange"
  charts_output_dir: "curseforge/charts"
  chart_width: "1000"
  chart_height: "360"
  chart_zero_baseline: "true"
  chart_y_ticks: "6"
  chart_x_label_every_days: "0"
  chart_show_value_labels: "false"
  chart_date_label_format: "yyyy-mm-dd"
  chart_show_generated_at: "true"
  chart_title_mode: "default"
  chart_title_text: ""

Chart options:

  • chart_types: total-trend, daily, weekly, monthly, yearly
  • chart_themes: black, slate, orange
  • chart_width, chart_height: pixel dimensions for all published SVG files
  • chart_zero_baseline: when true, Y-axis starts at 0 (enabled by default)
  • chart_y_ticks: Y-axis interval count (2..12) for denser/sparser value lines
  • chart_x_label_every_days: date label spacing (0 = auto spacing, 1 = every day)
  • chart_show_value_labels: render per-point numeric values above the line
  • chart_date_label_format: date labels (yyyy-mm-dd, yy/mm/dd, dd/mm, mm/dd, none)
  • chart_show_generated_at: show/hide Generated <date> footer text
  • chart_title_mode: title style (default, custom, none)
  • chart_title_text: custom title text (required only when chart_title_mode: "custom")
  • chart_output_path: primary chart path (first chart_types + first chart_themes)
  • charts_output_dir: directory for all matrix charts (<type>--<theme>.svg)

Note: chart_output_path publishes one primary chart, while charts_output_dir publishes the full chart matrix.
Note: for safety, output_path cannot overlap any chart output file when publish_chart is enabled.
Implementation note: chart types/themes/date/title enums are centralized in src/lib/chart-config.js.

Dense chart example (more Y values, daily date labels, and numbers):

with:
  publish_chart: "true"
  chart_types: "daily"
  chart_themes: "black"
  chart_zero_baseline: "true"
  chart_y_ticks: "10"
  chart_x_label_every_days: "1"
  chart_show_value_labels: "true"
  chart_date_label_format: "dd/mm"
  chart_show_generated_at: "true"
  chart_title_mode: "custom"
  chart_title_text: "My mod daily downloads"

Simple chart presets:

  • Clean default trend: keep defaults (chart_zero_baseline: "true", chart_y_ticks: "6", chart_x_label_every_days: "0")
  • Detail-heavy daily chart: set chart_types: "daily", chart_y_ticks: "10", chart_x_label_every_days: "1", chart_show_value_labels: "true"
  • Minimal labels (less clutter): keep chart_show_value_labels: "false" and use chart_x_label_every_days: "7" or higher

Embed the primary chart:

![Downloads trend](https://raw.githubusercontent.com/_OWNER_/_REPOSITORY_/stats-data/curseforge/downloads-trend.svg)

Embed a matrix chart directly:

![Downloads weekly orange](https://raw.githubusercontent.com/_OWNER_/_REPOSITORY_/stats-data/curseforge/charts/weekly--orange.svg)

Preview gallery (5 chart types):

Total trend preview Daily preview Weekly preview Monthly preview Yearly preview

Theme preview (same chart, 3 themes):

Theme black preview Theme slate preview Theme orange preview

Dashboard (optional)

You can publish a README-style dashboard Markdown file that summarises the current stats.

with:
  publish_dashboard: "true"
  dashboard_path: "curseforge/dashboard.md"

Behavior:

  • Enabled by default. Set publish_dashboard: "false" to turn it off.
  • On the first run the full dashboard is generated and written.
  • On later runs your customized dashboard is preserved: only the generated data tables are refreshed from the live payload. Titles, prose, badge rows, chart sections, and footers you edit stay as you left them.
  • The chart sections and chart images are generated on the first run and not overwritten afterwards, so you can customize them freely.
  • Values are rendered from the live payload, so the Window row always matches the current window_days.
  • If an existing dashboard file is missing the Window row (for example after a manual edit), the dashboard update is skipped for that run and the rest of the action continues normally.
  • Badge images use style=flat-square, logo=curseforge, and cacheSeconds=900.
  • When publish_chart is enabled, the dashboard links the published chart images.
  • dashboard_path must differ from output_path.

The dashboard is written to output_branch (default stats-data). To embed it in another README:

[![Downloads dashboard](https://raw.githubusercontent.com/_OWNER_/_REPOSITORY_/stats-data/curseforge/dashboard.md)](#)

Expected first-run result (nothing pre-seeded), so the file appears on the initial run:

  • Header: # <owner>/<repo> downloads
  • Badge row: total, day, week, month, year
  • Optional chart section when publish_chart is enabled
  • A ## Data table with update mode, the live window, snapshot count, partial flags, and generated time

Chart generator (copy-paste)

Generate Markdown image lines for selected chart types/themes.

node <<'NODE'
const owner = '_OWNER_';
const repo = '_REPOSITORY_';
const types = ['total-trend', 'daily', 'weekly', 'monthly', 'yearly'];
const themes = ['black', 'slate', 'orange'];
const base = `https://raw.githubusercontent.com/${owner}/${repo}/stats-data`;
for (const type of types) {
  for (const theme of themes) {
    console.log(`![Downloads ${type} ${theme}](${base}/curseforge/charts/${type}--${theme}.svg)`);
  }
}
NODE

PowerShell variant:

$owner = "_OWNER_"
$repo = "_REPOSITORY_"
$types = @("total-trend", "daily", "weekly", "monthly", "yearly")
$themes = @("black", "slate", "orange")
$base = "https://raw.githubusercontent.com/$owner/$repo/stats-data"
foreach ($type in $types) {
  foreach ($theme in $themes) {
    Write-Output "![Downloads $type $theme]($base/curseforge/charts/$type--$theme.svg)"
  }
}

Badge generator (copy-paste)

Generate all badge markdown lines for a repo.

node <<'NODE'
const owner = '_OWNER_';
const repo = '_REPOSITORY_';
const src = `https://raw.githubusercontent.com/${owner}/${repo}/stats-data/curseforge/downloads.json`;
const url = encodeURIComponent(src);
const definitions = [
  ['total', '$.stats.total', '0A7EA4'],
  ['day', '$.stats.day', '1E8E3E'],
  ['week', '$.stats.week', '0069C2'],
  ['month', '$.stats.month', 'B26A00'],
  ['year', '$.stats.year', '6A1B9A'],
  ['profile', '$.profile.defaultMode', '5E35B1'],
];
for (const [metric, query, color] of definitions) {
  const label = encodeURIComponent(`downloads/${metric}`);
  console.log(`![Downloads ${metric}](https://img.shields.io/badge/dynamic/json?url=${url}&query=${encodeURIComponent(query)}&label=${label}&color=${color})`);
}
NODE

PowerShell variant:

$owner = "_OWNER_"
$repo = "_REPOSITORY_"
$src = "https://raw.githubusercontent.com/$owner/$repo/stats-data/curseforge/downloads.json"
$u = [uri]::EscapeDataString($src)
$defs = @(
  @{ Name = "total"; Query = "$.stats.total"; Color = "0A7EA4" },
  @{ Name = "day"; Query = "$.stats.day"; Color = "1E8E3E" },
  @{ Name = "week"; Query = "$.stats.week"; Color = "0069C2" },
  @{ Name = "month"; Query = "$.stats.month"; Color = "B26A00" },
  @{ Name = "year"; Query = "$.stats.year"; Color = "6A1B9A" },
  @{ Name = "profile"; Query = "$.profile.defaultMode"; Color = "5E35B1" }
)
foreach ($d in $defs) {
  $label = [uri]::EscapeDataString("downloads/$($d.Name)")
  $query = [uri]::EscapeDataString($d.Query)
  Write-Output "![Downloads $($d.Name)](https://img.shields.io/badge/dynamic/json?url=$u&query=$query&label=$label&color=$($d.Color))"
}

Published JSON schema

Schema file: schema/downloads.schema.json

The action writes schemaVersion: "2" using this structure:

{
  "schemaVersion": "2",
  "owner": "N6REJ",
  "repo": "repository",
  "visibility": "public",
  "generatedAt": "2026-02-18T10:00:00.000Z",
  "stats": {
    "total": 9412,
    "day": 16,
    "week": 159,
    "month": 802,
    "year": 6543
  },
  "partial": {
    "day": false,
    "week": false,
    "month": true,
    "year": true
  },
  "periods": {
    "day": { "start": "2026-02-18", "end": "2026-02-18", "label": "2026-02-18" },
    "week": { "start": "2026-02-16", "end": "2026-02-22", "label": "2026-W08" },
    "month": { "start": "2026-02-01", "end": "2026-02-28", "label": "Feb 2026" },
    "year": { "start": "2026-01-01", "end": "2026-12-31", "label": "2026" }
  },
  "snapshots": {
    "windowDays": 365,
    "count": 31,
    "firstDate": "2026-01-18",
    "lastDate": "2026-02-18",
    "series": {
      "2026-02-18": 9412
    }
  },
  "profile": {
    "defaultMode": "daily",
    "hourlyEnabled": false
  }
}

Stability guarantees

For the v2 major line, the project follows these stability expectations:

  • Existing output keys in downloads.json will remain stable.
  • schemaVersion changes only for explicit schema migrations.
  • Existing action inputs and outputs are not removed without a major version bump.
  • Workflow template updates are additive or documented in release notes when behavior changes.

Note: schemaVersion: "2" changed week/month/year from rolling windows to calendar periods and added the periods block. The keys are unchanged; only their meaning (and the extra block) is new.

Inputs

Input Required Default Type Notes
token No empty string GitHub token for publishing (${{ secrets.GITHUB_TOKEN }} recommended)
owner No workflow repo owner string Target repo owner (publish destination)
repo No workflow repo name string Target repo name (publish destination)
curseforge_mod_id Yes – integer CurseForge mod (project) ID whose download total is tracked
cf_studio_api_key No empty string Optional CurseForge for Studios API key (${{ secrets.CF_STUDIO_API_KEY }}); when empty, the public cfwidget API is used (no key)
window_days No 365 integer Allowed range: 1..3650; automatically raised to at least the current day-of-year so the calendar-year baseline is retained
enable_hourly_profile No false boolean true/false, 1/0, yes/no accepted
output_branch No stats-data string Must be a valid git branch name
output_path No curseforge/downloads.json string Repo-relative file path; traversal blocked
min_refresh_minutes No 0 integer Optional cache window in minutes (0..10080); when >0, a fresh prior total can be reused
publish_chart No false boolean When true, publishes static SVG charts
chart_output_path No curseforge/downloads-trend.svg string Repo-relative path for the SVG chart
chart_types No total-trend csv Chart types list: total-trend,daily,weekly,monthly,yearly
chart_themes No black csv Chart themes list: black,slate,orange
charts_output_dir No curseforge/charts string Repo-relative directory where matrix chart files are written
chart_width No 1000 integer Chart width in pixels (640..4096)
chart_height No 360 integer Chart height in pixels (240..2160)
chart_zero_baseline No true boolean When true, Y-axis starts at 0
chart_y_ticks No 6 integer Y-axis interval count (2..12)
chart_x_label_every_days No 0 integer Date label spacing in days (0..365, 0 means auto)
chart_show_value_labels No false boolean When true, draws numeric labels above points
chart_date_label_format No yyyy-mm-dd enum Date labels: yyyy-mm-dd, yy/mm/dd, dd/mm, mm/dd, none
chart_show_generated_at No true boolean When true, shows Generated <date> footer
chart_title_mode No default enum default (owner/repo), custom (uses chart_title_text), or none
chart_title_text No empty string Custom title shown when chart_title_mode=custom (max 120 chars)
publish_dashboard No true boolean When true, publishes a README-style dashboard Markdown file built from the current stats
dashboard_path No curseforge/dashboard.md string Repo-relative path for the dashboard Markdown file

Outputs

  • owner, repo, generated_at
  • total, day, week, month, year
  • partial_day, partial_week, partial_month, partial_year
  • total_source (api or cache)
  • chart_output_path
  • chart_published (true when one or more chart SVGs were updated in this run)
  • chart_published_count, chart_total_count
  • chart_files (comma-separated generated chart paths)
  • dashboard_path, dashboard_published (true when the dashboard Markdown was updated in this run)
  • output_branch, output_path
  • published (true when file was updated, false when no material change was detected)

Testing

  • Style checks: scripts/style-check.js
  • Public test suite: tests/run-tests.js
  • Compatibility checks: compat/run-compat.js
  • Local command: npm test

Partial flags (plain language)

  • partial: false means the action has the exact earlier date needed for that comparison.
  • partial: true means the exact baseline date is missing, so the action uses an available snapshot and marks the comparison as incomplete.

For a new setup, expect weekly and monthly comparisons to remain partial until enough daily history has been collected.

Known limits

  • Weekly and monthly comparisons may be partial while the history is still growing.
  • The action records daily totals, not individual download events or unique users.
  • GitHub Raw and badge caching can delay when a new value becomes visible.
  • Running the action again on the same day may produce no new commit when nothing has changed.

Troubleshooting

Symptom Likely cause Exact fix
Badge shows no value JSON URL is wrong or file not published yet Open raw JSON URL directly and confirm it returns JSON
Badge says resource not found Repo is private Publish data from a public repo/branch for public badges
partial.week or partial.month is true Warm-up period or missing baseline snapshots Wait for enough snapshots; this is expected during early runs
Values look very low Mod has little/no download traffic Confirm the mod id is correct and the project has real downloads
Action fails with 401/403 CurseForge API key set but invalid, and the cfwidget fallback also rejected the request Check the CF_STUDIO_API_KEY secret, or remove it to use the keyless cfwidget fallback
Action fails with 404 Wrong CurseForge mod id Check curseforge_mod_id against your project's Project ID
Workflow reports no commit No material change between previous and current payload Check published output; this is expected when totals did not change
Push/write fails on stats-data Missing write permission or branch protection blocks Actions Set permissions: contents: write, pass token, allow Actions to push or use another branch
Wrong publish target repository data Owner/repo auto-resolution mismatch Set owner and repo explicitly in workflow with

FAQ

Why are my preview values so low?

If your mod has few downloads, totals and deltas will naturally stay low.

Do I need a GitHub Pages website?

No. stats-data is only used as a storage branch for the generated files.

More guides

Issue labels

  • Label definitions: .github/labels.json
  • Label sync workflow: .github/workflows/sync-labels.yml
  • Suggested issue labels for triage:
Label Purpose
bug Behavior is incorrect and needs a fix
enhancement Feature or UX improvement
question Usage/setup question
documentation Docs-only improvement
good first issue Beginner-friendly task
help wanted Maintainers are actively looking for contributors
breaking-change Behavior/input/output change requiring migration
performance API load/runtime efficiency work

Security

  • Grant the workflow only the repository permissions required for its selected output.
  • Store your CurseForge API key as the CF_STUDIO_API_KEY secret; never commit it to the repository.
  • Remember that public badges need a publicly readable result file.
  • Refer to the repository Security Policy for private vulnerability reporting.
  • Additional policies are available in .github/PRIVACY.md and .github/EULA.md.

Contributing

Contributions are welcome.

Contact

License

Licensed under the Apache License 2.0 (Apache-2.0).

See LICENSE.

Credits

Project concept based on justagwas/github-downloads-action.

About

Track total, daily, weekly, and monthly curseforge release downloads via a GitHub Action with badge-ready JSON and optional SVG charts.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages