cdnjs is the GitHub repository mirroring all library assets on cdnjs.cloudflare.com.
cdnjs relies on user-submitted pull requests and automatic updating to populate and update libraries. With hundreds of contributors and thousands of commits, it is very important that new libraries are added to cdnjs using the correct procedure.
Libraries that are actively-maintained on npmjs can be configured to be automatically updated. Other libraries that are not on npmjs should be updated manually.
cdnjs will host any production version of any JavaScript (JS) or Cascading Style Sheets (CSS) library, subject to appropriate licence permissions.
cdnjs will host JS, CSS, SWF and library image files. Note: cdnjs does not currently serve HTML or PHP files.
New libraries should have some indicator of popularity (e.g., GitHub stars or watchers) and purpose (e.g., a jQuery plugin to display images).
cdnjs maintainers and peer-reviewers need to know the origin of new libraries and updates (i.e., where you downloaded the files from).
Libraries that are actively-maintained on npmjs can be configured to be automatically updated. A cdnjs auto-update script runs every 15 minutes to check for new library versions on npmjs.
Each cdnjs library has a package.json file. This file contains required and sometimes optional information about how the library works. Auto-update is configured in package.json alongside other library information.
npmNameis the corresponding npmjs namenpmFileMapis a list of files to copy from npmjs to cdnjsbasePathis the path in the npmjs tarball; it will be ignored when files are copied to cdnjsfilesindicates the file(s) to copy and can be named (e.g., lodash.min.js) or wildcards (e.g., *.js).
"npmName": "lodash",
"npmFileMap": [{
"basePath": "/dist/",
"files": [
"*.js"
]
}],
The example in 2.3. parses the lodash tarball, which has this structure:
|__dist
| |__lodash.compat.js
| |__lodash.compat.min.js
| |__lodash.js
| |__lodash.min.js
| |__lodash.underscore.js
| |__lodash.underscore.min.js
|__LICENSE.txt
|__lodash.js
|__package.json
|__README.md
The auto-update process will locate dist (specified in basePath) and copy *.js (specified in files) to cdnjs, removing the dist path. The resulting files in cdnjs will be:
|__ajax
|__libs
|__lodash.js
|__x.y.z
|__lodash.compat.js
|__lodash.compat.min.js
|__lodash.js
|__lodash.min.js
|__lodash.underscore.js
|__lodash.underscore.min.js
…where x.y.z is the library version number, extracted from the package.json on npmjs.
When you locate a cdnjs library with a corresponding npmjs presence, the relevant package.json should be updated.
-Refer to 5.* below for instructions on forking, updating and committing changes to cdnjs.-
Coming soon - please refer to README.md.
Coming soon - please refer to README.md.
Coming soon - please refer to README.md.
Changes to cdnjs happen with the following process:
- fork the cdnjs repository to your GitHub account
- make the required changes to the forked repository
- run the pre-flight
npmcheck, resolve any errors - raise a pull request with appropriate information
- remove your forked repository after the merge
If these steps are followed, and everything works out, the update process is usually efficient and your library update will go live soon afterwards.
Forking the cdnjs repository is easy. Be aware that it is one of the largest repositories on GitHub (>3GB), and this should be a consideration if you choose to clone it to your computer.
To fork the repository via your browser, visit this link:
https://github.com/cdnjs/cdnjs/fork
Select your GitHub account for the destination and wait for the forking process to complete. Assuming you saw no errors, you should be able to access your fork of cdnjs from your own GitHub account:
https://github.com/your-github-username/cdnjs
…where your-github-username is, unsurprisingly, your GitHub username.
Change are made to your fork of cdnjs. These changes contribute to a pull request, which may be merged after examination by the cdnjs maintainers.
Changes to your fork can be made at GitHub using your browser, or on your computer using a git command line or graphical user interface.
-
If you intend to make a single, simple contribution to cdnjs you will likely find the browser experience more straightforward.
-
If you intend to make numerous contributions to cdnjs, you may find a local clone of your forked repository a better route.
Where possible, follow the existing file and directory structure for the library when adding a new version. Users should ideally be able to increment the version number reference in their projects to load a more recent version.
This is not always possible with major or minor version changes, especially with considerable changes, so please ask if you are not sure.
The GitHub website provides an easy-to-use interface to add and update simple libraries. A library containing a single or small number of text files is an ideal candidate for this route.
In your fork of cdnjs, navigate to ajax/libs:
https://github.com/your-github-username/cdnjs/tree/master/ajax/libs
…where, again, your-github-username is your GitHub username.
If you are updating an existing library, find it from the list. Click on the library name; you'll find a package.json file and one or more numbered directories. Each directory contains that version of the library, and that version only.
To add a new version of a library, create a new directory named after the new library version by clicking the + link near the top.
[INCOMPLETE]
Coming soon - please refer to README.md.
Coming soon - please refer to README.md.
Coming soon - please refer to README.md.
Coming soon - please refer to README.md.