Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
58 lines (39 loc) · 3.68 KB

CONTRIBUTING.md

File metadata and controls

58 lines (39 loc) · 3.68 KB
Raw

Contributing

Pull requests are disabled — please file an issue

This project does not accept pull requests. It is faster to tell a coding agent what to change than it is to review someone else's diff, so contributions come in as descriptions rather than patches.

Open an issue and pick New library, Library edit, or Other. Be as descriptive as you want; a thorough issue is worth more than a patch.

Listing criteria

It is now cheap to generate a plausible-looking library in an afternoon, so new entries must show they are established before being listed. A library must meet at least one of:

  1. Age: the GitHub repo or npm package was created at least 6 months ago and has had a commit or release in the last 6 months. Creation dates come from the GitHub and npm APIs, not from git commit dates.
  2. Stars: at least 100 GitHub stars.
  3. Downloads: at least 500 weekly npm downloads.

In addition, every entry must have an identifiable maintainer: a person or company with a public footprint that predates the library. Closed-source products without a GitHub repo meet this through the company behind them.

Entries that were listed before this rule are grandfathered. If your library does not qualify yet, wait until it does and open the issue then; it will be welcome.

Adding or updating a library

These are the steps a maintainer follows when acting on an issue.

  1. Skim lib/features.ts to learn the feature flags so you can describe the library's capabilities accurately.
  2. Add or edit a YAML file in data/ — see the existing files for the schema (title, home URL, GitHub repo, npm package, license, supported frameworks, and features). This powers the interactive site.
  3. Add or update the library's entry in README.md by hand, keeping the list alphabetical. Separate the link and description with a dash, start the description with an uppercase letter, and end it with a period.
  4. Run npx awesome-lint to confirm the README still conforms to the Awesome list format.
  5. Commit, referencing the issue so it closes.

All library descriptions are adapted from each package's home page.

Local development

  1. Create a GitHub Personal Access Token. You don't need to give it any scopes — it's just to increase the API rate limit.
  2. (Optional) Create an NPM Access Token for more reliable NPM API reads and to avoid rate limits.
  3. Make sure you have Node.js version 22 or later and the pnpm package manager installed.
  4. Check out the repo and run pnpm install.
  5. Create a .env file in the root directory with your tokens: 
    GITHUB_TOKEN=your_github_token_here
NPM_TOKEN=your_npm_token_here
  6. Run pnpm dev.
  7. Go to http://localhost:3000/ and bask in the wild splendor that is Awesome JavaScript Grids.

Information on each library lives in data/ and is parsed in lib/libraries.ts.

How it's built

License

The curated list itself (the contents of README.md and data/) is dedicated to the public domain under CC0 1.0. The source code that builds and serves this site is licensed under the MIT License.