The #1 free and open source CDN built to make life easier for developers.

---

cdnjs API Server

Looking for the documentation on our API?

cdnjs API docs

Getting Started

This project uses Node.js for development, and is deployed as a Cloudflare Worker. Please make sure you have a Node.js version installed that matches our defined requirement in the .nvmrc file for this project.

Included with this project is a dependency lock file. This is used to ensure that all installations of the project are using the same version of dependencies for consistency. You can install the dependencies following this lock file by running:

npm ci

Once the dependencies are installed, which includes the Wrangler CLI for Cloudflare Workers, the API server is now ready to run in development mode. To start the server in development mode, run:

npm run dev

This command will run the worker entirely locally, and you can access the API at http://localhost:8787 (note that the root path redirects to the docs).

Testing and More

Testing

This project uses Vitest to test the API server, with Cloudflare Workers' Vitest integration to run the worker locally for testing. The tests attempt to validate every route on the API to ensure that no breaking changes have been made, though there is no promise that this is perfect, a human should always review changes!

The Vitest test suite can be run at any time with the following command:

npm test

By default the test suite will run against a local version of the worker, and this is also done for any commit pushed to GitHub, for any pull requests, and prior to any staging/production deployment.

VITEST_EXTERNAL_API_URL can be set to target a deployed version of the API instead, which is used as the last step in our staging/production deployment workflows to verify the updated API worker.

Type-Checking

The API server is written in TypeScript, and the types are checked as part of the test suite. If you want to run the type-checking separately, you can use:

npm run types

If you've made changes to the Wrangler config file, such as adding a new environment variable or binding, you'll need to regenerate the worker types for these changes to be reflected in the type system. This can be done with:

npm run prepare:types

Linting

Included in this repository is an eslint config file to help with ensuring a consistent style and safely written codebase for the API server. To run eslint at any time, which checks all the TypeScript files, you can use:

npm run lint

eslint also provides automatic fixing capabilities, these can be run against the codebase with:

npm run lint:fix

Formatting

We also rely on our Prettier config and our editorconfig file config to ensure a consistent style and formatting across the codebase. To check that your code is properly formatted, you can run:

npm run format

prettier also provides automatic formatting capabilities. Via husky + lint-staged, this will be done for you when you commit changes, but you can also run it manually against the codebase with:

npm run format:fix

Error Logging

We use Sentry to handle our error logging. To enable Sentry in the API server, set the SENTRY_DSN environment variable in the Wrangler config file for the appropriate environment to a valid DSN URL from Sentry. The SENTRY_RELEASE environment variable can also be set to identify a specific release of the worker (our GitHub Actions workflows for deployments set this to the current commit hash).

Deployment

As this API server is written as a Cloudflare Worker, you can deploy it using the Wrangler CLI. This can be done manually, but this repository uses GitHub Actions to handle deploying to staging (api.cdnjs.dev) and production (api.cdnjs.com) based on commits to the staging/production branches, automatically handling not only deploying the worker but also creating a Sentry release with full source maps.

Before deploying, ensure that you generate the required KV namespace for the environment you are deploying to and update wrangler.toml to use the correct ID:

wrangler kv:namespace create CACHE --env=staging
# or
wrangler kv:namespace create CACHE --env=production

To deploy to staging (assuming you have write access to this repository), run make deploy-staging. This will force-push your latest local commit to the staging branch, which will trigger GitHub Actions to run and deploy your worker to Cloudflare Workers.

Similarly, for a production deployment, run make deploy-production. This will force-push to the production branch instead, and trigger the production GitHub Actions workflow.