spotify
web-scripts
Description
Build, lint, test, format, and release your JS/TS library. This CLI tool bundles all the necessary configuration and dependencies so you can focus on the code.
Usage
yarn add --dev @spotify/web-scripts huskyAdd the scripts and commit hooks to your package.json:
{
"scripts": {
"test": "web-scripts test",
"lint": "web-scripts lint",
"format": "web-scripts format",
"build": "web-scripts build",
"commit": "web-scripts commit",
"release": "web-scripts release"
},
"husky": {
"hooks": {
"commit-msg": "web-scripts commitmsg",
"pre-commit": "web-scripts precommit"
}
}
}If you plan to use web-scripts build to build ESM, CommonJS, and types for your library with ease, update your package.json to define the locations where those will end up. Read more about our the build script.
{
"main": "cjs/index.js",
"module": "esm/index.js",
"types": "types"
}Editor support steps
Add a root tsconfig.json:
{
"extends": "@spotify/web-scripts/config/tsconfig.json",
"include": ["src"]
}Add a root prettier.config.js:
module.exports = require('@spotify/web-scripts/config/prettier.config.js');Add a root .eslintrc.js:
module.exports = require('@spotify/web-scripts/config/eslintrc.js');Add a root jest.config.js:
module.exports = require('@spotify/web-scripts/config/jest.config.js');Watchers
Both web-scripts build and web-scripts test support a --watch flag which runs the underlying CLIs (tsc and jest) as watchers.
# re-compile the cjs, esm, and types on each change to your src with tsc
web-scripts build --watch
# re-run the tests that are relevant to your file changes with jest
web-scripts test --watchThe build script
web-scripts build runs three parallel calls to the TypeScript compiler.
- One of them transpiles the files as CommonJS and outputs it to the
cjsdirectory. Your repo should have"cjs/index.js"set asmainin your package.json. You can turn this off using--no-cjswhen running build. - Another does the exact same thing but only transpiles to EcmaScript modules. This is super helpful if your consuming project is using Babel or TypeScript, and you'll end up avoiding playing games of transpilation telephone along the way. Your repo should have
"esm/index.js"set asmodulein your package.json if using this. You can turn this off with the--no-esmflag when running build. - Finally, tsc will be run to output type definitions. Your repo should have the
"types"directory set astypesin your package.json if using this. You can turn this off with the--no-typesflag when running build.
These parallel builds are set up to share resources and work efficiently.
If you need to use Babel for some reason, that's ok! Simply use babel directly instead of using web-scripts build. Teams inside Spotify mix and match which scripts they use to serve their needs. In many cases, tsc is all you need and is lighter and simpler to set up.
Setting up CI publishing (Travis CI)
The following steps should be from your local repository folder.
(Optional but probably mandatory): Visit https://travis-ci.com/account/repositories and click "Sync Account" otherwise the Travis CLI may not be able to register your ENV vars later.
- Add a basic .travis.yaml. You probably want something like:
language: node_js
node_js:
- '14'
branches:
only:
- master
cache:
yarn: true
directories:
- node_modules
before_install:
- curl -o- -L https://yarnpkg.com/install.sh | bash -s
- export PATH="$HOME/.yarn/bin:$PATH"
script:
- yarn lint
- yarn test- Append a "release" stage to the
jobs:that invokesweb-scripts release:
jobs:
include:
- stage: release
node_js: lts/*
script: skip # do not run tests again
deploy:
provider: script
skip_cleanup: true
script:
- yarn web-scripts release # or `yarn release` if you defined it in your package.json scripts- Install the travis CI CLI:
gem install travis - Create an NPM token:
https://www.npmjs.com/settings/[NPM USERNAME]/tokens(scope: Read and Publish) - Set the secure ENV var:
travis env set NPM_TOKEN YOUR-NPM-TOKEN - Create a Github Token:
https://github.com/settings/tokens(required scope:public_repo!) - Set the secure ENV var:
travis env set GH_TOKEN YOUR-GH-TOKEN - Commit all your changes with
yarn commit, and push.
If you use a scoped public package, such as @yourusername/packagename, then you'll need explicitly set in your package.json:
"publishConfig": {
"access": "public"
},Otherwise you'll receive an error during release like "You must sign up for private packages" or a missing flag --access=public.
Contributing
To start working in the repo:
yarn
yarn bootstrapThis library provides shared scripts and configs for creating a library at Spotify. It tries to use as much of those scripts and configs for itself, which is why the bootstrap task is required above. Otherwise, you can run within this package itself:
yarn lint
yarn build
yarn test