mirror of
https://github.com/wahyd4/cdnjs.git
synced 2026-08-29 06:36:08 +10:00
107 lines
5.5 KiB
Markdown
107 lines
5.5 KiB
Markdown
<a href="http://travis-ci.org/cdnjs/cdnjs"><img src="https://secure.travis-ci.org/cdnjs/cdnjs.png" alt="Build Status" style="max-width:100%;"></a>
|
|
|
|
# cdnJS Script Repository
|
|
|
|
cdnJS is the repository mirroring all scripts on `cdnjs.cloudflare.com`, created and maintained by [Thomas Davis](https://twitter.com/neutralthoughts), [Ryan Kirkman](https://twitter.com/ryan_kirkman) and [Lachlan Collins](http://plus.google.com/116251728973496544370?prsrc=3)
|
|
|
|
We will host any version of any library, subject to popularity and licence permissions.
|
|
|
|
__Libraries must have notable popularity: 100 stars or watchers on GitHub is a good example, but as long as reasonable popularity can be demonstrated the library will be added.__
|
|
|
|
Evidence of popularity should be included in your pull request if the GitHub project doesn't indicate this already.
|
|
|
|
Please raise a pull request for an older version of a library if your site still uses it, and also for proposals for new libraries.
|
|
|
|
## Adding a new or updating an existing library
|
|
|
|
cdnJS relies on user's pull requests and automatic updating via `npm` to populate libraries. To add a new library, or update an existing library outside of `npm`, start by [forking the cdnJS repo](https://github.com/cdnjs/cdnjs/fork) to your own GitHub account.
|
|
|
|
If you're adding/modifying outside of the GitHub browser interface, for example on the command line or with the GitHub desktop app, you will need to additionally install `node` locally. For more information on installing `node`, please refer to [nodejs.org](http://nodejs.org).
|
|
|
|
When you have forked the cdnJS repo, add your library to it. Libraries are stored in the `ajax/libs` directory. Each library has its own subdirectory of `ajax/libs` and each version of the library has its own subdirectory of the library directory name, for example:
|
|
|
|
```
|
|
/ajax/libs/jquery/2.0.0/
|
|
```
|
|
|
|
## Conventions
|
|
|
|
You should consider the following when adding to or updating the library:
|
|
|
|
* Filenames should **not** include a version number and be **lowercase**. This is OK: `useful.min.js`, but this is not: `useful-2.0.1.min.js`.
|
|
|
|
* JavaScript & CSS files should be minified to reduce network and browser overhead. If the library doesn't already provide a minified version, cdnJS's preferred minifier is [UglifyJS](http://marijnhaverbeke.nl/uglifyjs "UglifyJS")
|
|
|
|
* If you are updating an existing library, try to keep consistent with the existing structure. There will be occasions, particularly with major version increments, where this is not practical; if there are significant changes in the file structure, please note this in your pull request.
|
|
|
|
|
|
## Create or update `package.json`
|
|
|
|
Each library has a corresponding `package.json`, written in `npm` format (see `test/schemata/npm-package.json` for details or use another `package.json` to crib from - it's very simple). When an existing library is updated, the details in `package.json` should be checked and updated where required. For example, if a new version of the library is added, the version number may need changing.
|
|
|
|
## Run `npm test` to check all is well
|
|
|
|
If you're updating the library outside of `npm` or the GitHub browser, you should run `npm test` from the library directory to ensure everything is OK. If you run `npm test` and see no errors, all is well; resolve any errors before you raise your pull request and re-run `npm test` to ensure everything works.
|
|
|
|
## Pull request pre-flight checks
|
|
|
|
* Have you followed the library directory structure?
|
|
* Does a valid and accurate `package.json` exist for the library?
|
|
* Have you minified JavaScript and CSS?
|
|
* Did `npm test` check out OK?
|
|
|
|
...if so, you're ready to raise a pull request.
|
|
|
|
## Raising a pull request
|
|
|
|
Please restrict your pull request to one library. From a maintenance standpoint, it's much more straightforward to process pull requests where there is one commit for one library.
|
|
|
|
In your pull request title, tell us what you're doing. If you are the author of the library, please add `[author]` to the pull request title.
|
|
|
|
Please include the following in your pull request:
|
|
|
|
* The origin of your library files (e.g., where you downloaded it)
|
|
* If it isn't clear, how you found the version of the script (e.g., `Source: http://github.com/example/releases/1.2.3.zip`)
|
|
* Evidence of popularity if the GitHub numbers don't indicate popularity.
|
|
|
|
## Enabling `npm` auto update
|
|
|
|
cdnJS automatically updates libraries that are known to be hosted on `npm` e.g., Lodash. This auto-update script runs automatically every 4 hours.
|
|
|
|
To add an `npm` hook to a library, update the `package.json` with configuration details and submit your pull request. An example configuration:
|
|
|
|
```
|
|
// Lodash package.json
|
|
// ...
|
|
"npmName": "lodash",
|
|
"npmFileMap": [{
|
|
"basePath": "/dist/",
|
|
"files": [
|
|
"*.js"
|
|
]
|
|
}],
|
|
// ...
|
|
```
|
|
|
|
* `npmName` should map to the name of the library on `npm`
|
|
* `npmFileMap` is a list of files to take from the `npm` tarball and host on the CDN
|
|
* `basePath` will be ignored when copying over to the CDN
|
|
* `files` is a pattern matcher allowing selection of multiple files
|
|
|
|
The above example looks in the tarball whose structure might look like this:
|
|
|
|
```
|
|
- dist/lodash.js
|
|
- dist/lodash.min.js
|
|
```
|
|
|
|
The auto-update process will look for `dist/*` inside the named tarball and copy the JavaScript file(s) to cdnJS, minus the `dist` path. The resulting files in cdnJS will be:
|
|
|
|
```
|
|
ajax/libs/lodash.js/1.0.0/lodash.js
|
|
ajax/libs/lodash.js/1.0.0/lodash.min.js
|
|
```
|
|
|
|
## Extensions, Plugins, Resources
|
|
|
|
[Extensions, Plugins, Resources](https://github.com/cdnjs/cdnjs/wiki/Extensions%2C-Plugins%2C-Resources) |