RFC: a list of commands for NPM script in InstantSearch projects

common-npm-script.md

Standardized NPM commands for InstantSearch libraries

Pattern using commands

• command: used for main commands
• command:sub_command: used for commands related to a bigger command (build:umd is for buildbing

There should not probably be a third level.

Common commands:

• start: Launch the dev mode (TBD)
• build: Prepare prod builds
• test: Launch all tests
• test:fix: Updates snapshots
• lint: Run the linter on the source
• lint:fix: Automatically fixes the linter errors (when possible)
• docs: builds the production-ready documentation
• docs:watch: auto rebuilding doc
• release: automated release script (handles git merge to master, version update, changelog update, npm)
• changelog: display the unreleased changelog entries
• changelog:fix: writes down the newest entries of the changelog

Common subcommands

• *:watch: watch the files for update and rerun the command (might not be implemented like but that's the expect behavior)
• *:fix: fix or update some code

Reference of current package.json

Instantsearch.js

• "build": "./scripts/build.sh",
• "dev": "./scripts/dev.sh",
• "dev-novel": "NODE_ENV=development webpack-dev-server --config dev/webpack.config.js",
• "doctoc": "doctoc --no-title --maxlevel 3 README.md CONTRIBUTING.md",
• "lint": "npm run lint:js && npm run lint:css",
• "lint:js": "eslint .",
• "lint:css": "./scripts/lint-css",
• "docs:build:dev": "./scripts/docs/build-dev.sh",
• "docs:publish": "./scripts/docs/publish.sh",
• "finish-release": "./scripts/finish-release.sh",
• "view-changelog": "conventional-changelog -p angular",
• "release": "./scripts/release.js",
• "test": "jest",
• "test:watch": "jest --watch --bail",
• "test:size": "bundlesize",
• "release-maintenance": "./scripts/release-maintenance.sh",
• "test:functional": "wdio functional-tests/wdio.conf.js",
• "test:functional:dev": "babel-node scripts/dev-functional-tests",
• "test:functional:dev:debug-server": "PORT=9090 babel-node scripts/dev-functional-tests-debug-server",
• "argos": "argos upload functional-tests/screenshots --token $ARGOS_TOKEN || true",
• "serve": "./scripts/serve.sh",
• "fix:prettier": "eslint --fix -c .eslintrc.js ."

react-instantsearch

• "boot": "./scripts/boot.sh",
• "changelog": "conventional-changelog --preset angular --output-unreleased",
• "start": "NODE_ENV=development babel-node docgen/start.js & NODE_ENV=development yarn docs:storybook-start & wait",
• "docs:build": "babel-node docgen/build.js && yarn docs:storybook-build-production",
• "docs:deploy-production": "NODE_ENV=production yarn docs:build && babel-node scripts/gh-pages.js",
• "docs:build-preview": "./scripts/docs:build-preview.sh",
• "docs:deploy-preview": "NODE_ENV=production yarn docs:build-preview && rm -f preview.zip && zip -r -9 preview.zip docs-production/ && netlify deploy && rm preview.zip",
• "release": "NODE_ENV=production ./scripts/release.sh",
• "lint": "eslint .",
• "lint:fix": "eslint . --fix",
• "docs:doctoc": "doctoc --maxlevel 1 README.md",
• "test": "./scripts/test.sh",
• "test:recipes": "./scripts/test:recipes.sh",
• "test:build": "NODE_ENV=production ./scripts/test:build.sh",
• "test:regressions": "webpack --config test/regressions/webpack.config.js && rm -rf test/screenshots && happo run && babel-node ./test/regressions/normalize.js",
• "test:size": "bundlesize",
• "argos": "argos upload test/screenshots --token $ARGOS_TOKEN || true",
• "dev": "jest --watch --bail",
• "docs:storybook-start": "start-storybook -p 6006 -c ./storybook -s ./storybook/public",
• "docs:storybook-build-production": "build-storybook -s ./storybook/public -o docs-production/react-instantsearch/storybook -c ./storybook"

Vue-instantsearch

• "build": "yarn run build:cjs && yarn run build:es && yarn run build:umd",
• "build:cjs": "rollup -c ./build/rollup.cjs.config.js",
• "build:es": "rollup -c ./build/rollup.es.config.js",
• "build:umd": "rollup -c ./build/rollup.umd.config.js",
• "storybook": "start-storybook -p 9001 -c .storybook",
• "storybook:build": "build-storybook -c .storybook -o docs/dist/stories",
• "docs:build": "cd docs && yarn && yarn build",
• "docs:build:dev": "cd docs && yarn && yarn build:dev",
• "docs:watch": "cd docs && yarn && yarn dev",
• "docs:deploy": "cd docs && yarn && yarn deploy",
• "test": "jest --verbose --coverage && yarn run lint",
• "test:update": "jest --verbose --updateSnapshot",
• "test:watch": "jest --verbose --watchAll --notify",
• "lint": "eslint --ext .js,.vue .",
• "lint:fix": "eslint --ext .js,.vue . --fix",
• "changelog": "conventional-changelog --preset angular --infile CHANGELOG.md --same-file",
• "changelog:unreleased": "conventional-changelog --preset angular --output-unreleased"

Angular-instantsearch

• "build": "./scripts/build.sh",
• "lint": "tslint src//*.ts examples//*.ts",
• "dev": "webpack-dev-server --config webpack.demo.js --inline --progress --host 0.0.0.0 --port 3000",
• "test": "jest",
• "test:ci": "yarn lint && jest --runInBand && yarn build",
• "test:watch": "jest --watch",
• "examples:ecommerce": "./scripts/run-example.sh e-commerce",
• "examples:ecommerce:build": "./scripts/build-example.sh e-commerce",
• "examples:router": "./scripts/run-example.sh angular-router",
• "examples:router:build": "./scripts/build-example.sh angular-router",
• "release": "./scripts/release.sh",
• "netlify": "./scripts/netlify.sh",
• "doc:publish": "git subtree push --prefix doc origin gitbook"

Helper

• "watch": "watchify index.js -v -s algoliasearchHelper -o dist/algoliasearch.helper.js",
• "build": "./scripts/build.sh",
• "dev": "DEBUG=zuul* zuul --no-coverage --local 8090 test/run.js",
• "dev-coverage": "DEBUG=zuul* zuul --local 8090 test/run.js",
• "lint": "scripts/lint.sh",
• "lint:watch": "onchange 'src//*js' 'index.js' 'test//*js' '.eslintrc' -- npm run -s lint",
• "open": "sleep 1 && opn http://localhost:8080/examples",
• "examples": "npm run build & npm run open & http-server .",
• "doc": "gulp --gulpfile documentation-src/build.gulp.js doc",
• "doc:watch": "gulp --gulpfile documentation-src/build.gulp.js doc:watch",
• "doc:publish": "yarn run doc && gh-pages -d documentation",
• "doc:staging": "scripts/staging-doc.sh",
• "readme:toc": "doctoc --notitle README.md --maxlevel 3",
• "test-ci": "scripts/test-ci.sh",
• "test": "scripts/test.sh",
• "test:unit": "ONLY_UNIT=true scripts/test.sh",
• "test-node": "clear && node test/run",
• "test:watch": "onchange '{src,test}/**/*.js' 'index.js' -- npm run test-node",
• "test:perf": "node ./test/perf/index.js",
• "release": "git checkout dist/ && rm -rf node_modules && yarn && ./scripts/release.js",
• "changelog:view-last": "conventional-changelog -u -n scripts/conventional-changelog/",
• "changelog:update": "conventional-changelog -i CHANGELOG -s -u -n scripts/conventional-changelog/"

JS Client

• "build": "./scripts/build",
• "dev": "APP_ENV=development DEBUG=zuul* zuul --no-coverage --local 8080 -- test/run-browser.js",
• "dev-integration": "APP_ENV=development DEBUG=zuul* zuul --no-coverage --local 8080 -- test/run-integration.js",
• "examples": "http-server . -a 0.0.0.0",
• "watch": "watchify index.js -d -v -s algoliasearch -o dist/algoliasearch.js",
• "release": "git clean dist/ -f && git checkout dist/ && yarn && ./scripts/release && APP_ENV=production npm run build",
• "test": "./scripts/test",
• "test-ci": "./scripts/test-ci",
• "lint": "./scripts/lint"

Nice initiative thanks for taking the time to do so!

Couple thoughts:

• start (TBD) should always launch the DOC website in watch mode (I want to start the website)
• I would add dev that would be about launching the unit tests in watch mode (I want to dev the library)
• if start is the docs watch mode, I would only have docs:build
• changelog:fix even if I understand the will to have common sub commands (like fix), this seems a bit cryptic compared to the actual behaviour of the command. I would expect this one to somehow fix the whitespace etc.. And not update the changelog.
  • since the release command is the one updating the changelog in most cases (or should) then I would just have changelog and changelog:update. Or not even changelog:update if there's no way we will ever run it manually if the release scripts are full-filling all our needs (release from develop, release from master in case of important patch, release a beta from a branch)

Well start is a special command which represents the main action you do with a codebase (I guess) and I don't know if doing documentation is more common than coding / testing the code.

I have had the need for the changelog to give me an idea as maintainer of the amount of features / fix to be released.

The whole fix subcommand is indeed an attempt to fit a common command, and indeed it does not work very well.

Agree with @bobylito the start command should be the main action, so the dev env make sense IMO. You can still launch the docs in a separate terminal. Also with the actual behaviour the start command launch both, but when one of the process crash (it happens) you'll need to restart both. IMO it's better to keep them separately, most of the time you don't code & write the documentation at the same time.