Simple and speedy package manager

Simple: Cotton works with web applications, including those built with React, Next.js, Vite, TypeScript, ESLint, and more.

Speedy: With a fast network, cotton install runs faster than rm -rf node_modules.

Trouble free: Ever run into errors when you forget to run yarn? No more. With Cotton, node_modules would never get out of sync.

Quickstart for Netlify • Cloudflare Pages

Benchmarks

Bun's benchmark

Installing packages used by create-react-app:

See benchmark for more information.

Installation

Install from source

cargo install --locked --git https://github.com/danielhuang/cotton

Install compiled artifact (Linux-only)

Download and install the compiled binary:

sudo curl -f#SL --compressed --tlsv1.2 https://api.cirrus-ci.com/v1/artifact/github/danielhuang/cotton/Build/binaries/target/x86_64-unknown-linux-gnu/release/cotton -o /usr/local/bin/cotton
sudo chmod +x /usr/local/bin/cotton

Get started

Install packages

cotton install

This will install packages to node_modules and save cotton.lock if needed.

Run a script

To run the start script:

cotton run start

To automatically restart the script when package.json changes:

cotton run start --watch package.json

Unlike other package managers, Cotton does not require installing packages before running scripts. Missing packages will be installed on-demand automatically.

Update package versions

cotton update

This will load the latest available versions of dependencies (including transitive dependencies) and save registry information to cotton.lock. Specified versions in package.json are not modified.

Allow install scripts

If dependencies require install scripts (such as puppeteer or electron) to function, add this to cotton.toml:

allow_install_scripts = true

Using as part of CI/CD?

In order to use Cotton, you have 2 options:

• Commit the binary to the repository, working similarly to committing Yarn 2+ (recommended)
• Download Cotton on-demand as part of the build process

If the binary is committed to the repository, use ./cotton instead of cotton.

Using Netlify

First, modify the configuration in netlify.toml, and add these lines:

[build.environment]
  NPM_FLAGS="--version"

Make sure yarn.lock is not present.

Add a command to remove node_modules from the build directory after the build finishes. Since Netlify stores its cache using tar, caching and extracting node_modules would be slower than reinstalling using Cotton.

For example, if the build command was

cotton run build

Add another command to the end:

cotton run build && mv node_modules _node_modules

This would disable Netlify's cache.

Using Cloudflare Pages

Set the environment variable NPM_FLAGS to --version. Make sure that there is no yarn.lock in the repository.

Limitations

• Cotton does not currently support Git repositories or local paths as dependencies; only registries and direct urls are supported.