diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-npmcli-docs.yml similarity index 93% rename from .github/workflows/ci-docs.yml rename to .github/workflows/ci-npmcli-docs.yml index d93027f72a380..9906b3bb791e6 100644 --- a/.github/workflows/ci-docs.yml +++ b/.github/workflows/ci-npmcli-docs.yml @@ -1,6 +1,6 @@ # This file is automatically added by @npmcli/template-oss. Do not edit. -name: CI - docs +name: CI - @npmcli/docs on: workflow_dispatch: @@ -71,9 +71,9 @@ jobs: - name: Reset Deps run: node . run resetdeps - name: Lint - run: node . run lint --ignore-scripts -w docs + run: node . run lint --ignore-scripts -w @npmcli/docs - name: Post Lint - run: node . run postlint --ignore-scripts -w docs + run: node . run postlint --ignore-scripts -w @npmcli/docs test: name: Test - ${{ matrix.platform.name }} - ${{ matrix.node-version }} @@ -119,7 +119,7 @@ jobs: - name: Add Problem Matcher run: echo "::add-matcher::.github/matchers/tap.json" - name: Test - run: node . test --ignore-scripts -w docs + run: node . test --ignore-scripts -w @npmcli/docs - name: Check Git Status if: matrix && matrix.platform.os != 'windows-latest' run: node scripts/git-dirty.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 78454247c72e7..57ea1212be5e1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -135,32 +135,6 @@ jobs: if: matrix && matrix.platform.os != 'windows-latest' run: node scripts/git-dirty.js - check-docs: - name: Check Docs - if: github.repository_owner == 'npm' - runs-on: ubuntu-latest - defaults: - run: - shell: bash - steps: - - name: Checkout - uses: actions/checkout@v3 - - name: Setup Git User - run: | - git config --global user.email "npm-cli+bot@github.com" - git config --global user.name "npm CLI robot" - - name: Setup Node - uses: actions/setup-node@v3 - with: - node-version: 18.x - cache: npm - - name: Reset Deps - run: node . run resetdeps - - name: Make Docs - run: make freshdocs - - name: Check Git Status - run: node scripts/git-dirty.js - licenses: name: Check Licenses if: github.repository_owner == 'npm' diff --git a/.github/workflows/create-cli-deps-pr.yml b/.github/workflows/create-cli-deps-pr.yml index e0fd97fa206b3..e5bd2ccdd1315 100644 --- a/.github/workflows/create-cli-deps-pr.yml +++ b/.github/workflows/create-cli-deps-pr.yml @@ -64,7 +64,6 @@ jobs: echo "Prepping CLI repo for release" cd cli git checkout "$npm_vtag" - make make release echo "Removing old npm" diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md index c945f9e18637f..faa7517bdfc41 100644 --- a/DEPENDENCIES.md +++ b/DEPENDENCIES.md @@ -119,6 +119,7 @@ graph LR; npm-->npmcli-arborist["@npmcli/arborist"]; npm-->npmcli-ci-detect["@npmcli/ci-detect"]; npm-->npmcli-config["@npmcli/config"]; + npm-->npmcli-docs["@npmcli/docs"]; npm-->npmcli-eslint-config["@npmcli/eslint-config"]; npm-->npmcli-fs["@npmcli/fs"]; npm-->npmcli-git["@npmcli/git"]; @@ -192,6 +193,10 @@ graph LR; npmcli-config-->proc-log; npmcli-config-->read-package-json-fast; npmcli-config-->semver; + npmcli-docs-->ignore-walk; + npmcli-docs-->npmcli-eslint-config["@npmcli/eslint-config"]; + npmcli-docs-->npmcli-fs["@npmcli/fs"]; + npmcli-docs-->npmcli-template-oss["@npmcli/template-oss"]; npmcli-fs-->semver; npmcli-git-->npm-pick-manifest; npmcli-git-->npmcli-promise-spawn["@npmcli/promise-spawn"]; @@ -255,6 +260,7 @@ graph LR; ansi-styles-->color-convert; are-we-there-yet-->delegates; are-we-there-yet-->readable-stream; + argparse-->sprintf-js; babel-code-frame-->babel-highlight["@babel/highlight"]; babel-core-->babel-code-frame["@babel/code-frame"]; babel-core-->babel-generator["@babel/generator"]; @@ -273,13 +279,10 @@ graph LR; babel-core-->semver; babel-core-->source-map; babel-generator-->babel-types["@babel/types"]; + babel-generator-->jridgewell-gen-mapping["@jridgewell/gen-mapping"]; babel-generator-->jsesc; - babel-generator-->source-map; - babel-helper-environment-visitor-->babel-types["@babel/types"]; - babel-helper-function-name-->babel-helper-get-function-arity["@babel/helper-get-function-arity"]; babel-helper-function-name-->babel-template["@babel/template"]; babel-helper-function-name-->babel-types["@babel/types"]; - babel-helper-get-function-arity-->babel-types["@babel/types"]; babel-helper-hoist-variables-->babel-types["@babel/types"]; babel-helper-module-imports-->babel-types["@babel/types"]; babel-helper-module-transforms-->babel-helper-environment-visitor["@babel/helper-environment-visitor"]; @@ -325,6 +328,7 @@ graph LR; babel-traverse-->babel-types["@babel/types"]; babel-traverse-->debug; babel-traverse-->globals; + babel-types-->babel-helper-string-parser["@babel/helper-string-parser"]; babel-types-->babel-helper-validator-identifier["@babel/helper-validator-identifier"]; babel-types-->to-fast-properties; bin-links-->cmd-shim; @@ -338,7 +342,6 @@ graph LR; bl-->inherits; bl-->readable-stream; brace-expansion-->balanced-match; - brace-expansion-->concat-map; buffer-->base64-js; buffer-->ieee754; builtins-->semver; @@ -376,7 +379,6 @@ graph LR; columnify-->strip-ansi; columnify-->wcwidth; combined-stream-->delayed-stream; - convert-source-map-->safe-buffer; cssstyle-->cssom; data-urls-->abab; data-urls-->whatwg-mimetype; @@ -387,18 +389,6 @@ graph LR; detab-->repeat-string; dezalgo-->asap; dezalgo-->wrappy; - docs-->cmark-gfm; - docs-->jsdom; - docs-->marked-man; - docs-->mdx-js-mdx["@mdx-js/mdx"]; - docs-->mkdirp; - docs-->npmcli-eslint-config["@npmcli/eslint-config"]; - docs-->npmcli-fs["@npmcli/fs"]; - docs-->npmcli-promise-spawn["@npmcli/promise-spawn"]; - docs-->npmcli-template-oss["@npmcli/template-oss"]; - docs-->tap; - docs-->which; - docs-->yaml; domexception-->webidl-conversions; encoding-->iconv-lite; end-of-stream-->once; @@ -410,6 +400,7 @@ graph LR; form-data-->asynckit; form-data-->combined-stream; form-data-->mime-types; + front-matter-->js-yaml; fs-minipass-->minipass; gauge-->aproba; gauge-->console-control-strings; @@ -483,6 +474,13 @@ graph LR; is-cidr-->cidr-regex; is-core-module-->has; is-fullwidth-code-point-->number-is-nan; + jridgewell-gen-mapping-->jridgewell-set-array["@jridgewell/set-array"]; + jridgewell-gen-mapping-->jridgewell-sourcemap-codec["@jridgewell/sourcemap-codec"]; + jridgewell-gen-mapping-->jridgewell-trace-mapping["@jridgewell/trace-mapping"]; + jridgewell-trace-mapping-->jridgewell-resolve-uri["@jridgewell/resolve-uri"]; + jridgewell-trace-mapping-->jridgewell-sourcemap-codec["@jridgewell/sourcemap-codec"]; + js-yaml-->argparse; + js-yaml-->esprima; jsdom-->abab; jsdom-->acorn-globals; jsdom-->acorn; @@ -697,7 +695,6 @@ graph LR; npm-->cli-columns; npm-->cli-table3; npm-->columnify; - npm-->docs; npm-->fastest-levenshtein; npm-->fs-minipass; npm-->glob; @@ -741,6 +738,7 @@ graph LR; npm-->npmcli-arborist["@npmcli/arborist"]; npm-->npmcli-ci-detect["@npmcli/ci-detect"]; npm-->npmcli-config["@npmcli/config"]; + npm-->npmcli-docs["@npmcli/docs"]; npm-->npmcli-eslint-config["@npmcli/eslint-config"]; npm-->npmcli-fs["@npmcli/fs"]; npm-->npmcli-git["@npmcli/git"]; @@ -847,6 +845,19 @@ graph LR; npmcli-config-->semver; npmcli-config-->walk-up-path; npmcli-disparity-colors-->ansi-styles; + npmcli-docs-->cmark-gfm; + npmcli-docs-->front-matter; + npmcli-docs-->ignore-walk; + npmcli-docs-->isaacs-string-locale-compare["@isaacs/string-locale-compare"]; + npmcli-docs-->jsdom; + npmcli-docs-->marked-man; + npmcli-docs-->mdx-js-mdx["@mdx-js/mdx"]; + npmcli-docs-->mkdirp; + npmcli-docs-->npmcli-eslint-config["@npmcli/eslint-config"]; + npmcli-docs-->npmcli-fs["@npmcli/fs"]; + npmcli-docs-->npmcli-template-oss["@npmcli/template-oss"]; + npmcli-docs-->tap; + npmcli-docs-->yaml; npmcli-fs-->gar-promisify["@gar/promisify"]; npmcli-fs-->semver; npmcli-git-->lru-cache; @@ -1042,6 +1053,7 @@ graph LR; tough-cookie-->psl; tough-cookie-->punycode; tough-cookie-->universalify; + tough-cookie-->url-parse; tr46-->punycode; tunnel-agent-->safe-buffer; type-check-->prelude-ls; @@ -1065,6 +1077,8 @@ graph LR; unist-util-visit-->unist-util-visit-parents; unist-util-visit-parents-->types-unist["@types/unist"]; unist-util-visit-parents-->unist-util-is; + url-parse-->querystringify; + url-parse-->requires-port; validate-npm-package-license-->spdx-correct; validate-npm-package-license-->spdx-expression-parse; validate-npm-package-name-->builtins; @@ -1102,6 +1116,6 @@ packages higher up the chain. - pacote, libnpmaccess, libnpmhook, libnpmorg, libnpmsearch, libnpmteam, npm-profile - npm-registry-fetch, libnpmversion - @npmcli/git, make-fetch-happen, @npmcli/config, init-package-json - - @npmcli/installed-package-contents, @npmcli/map-workspaces, cacache, npm-pick-manifest, @npmcli/run-script, read-package-json, @npmcli/query, readdir-scoped-modules, promzard - - npm-bundled, read-package-json-fast, @npmcli/fs, unique-filename, @npmcli/promise-spawn, npm-install-checks, npm-package-arg, npm-packlist, normalize-package-data, @npmcli/package-json, bin-links, nopt, npmlog, parse-conflict-json, dezalgo, read - - npm-normalize-package-bin, @npmcli/name-from-folder, json-parse-even-better-errors, semver, @npmcli/move-file, fs-minipass, infer-owner, ssri, unique-slug, hosted-git-info, proc-log, validate-npm-package-name, @npmcli/node-gyp, ignore-walk, minipass-fetch, cmd-shim, read-cmd-shim, write-file-atomic, abbrev, are-we-there-yet, gauge, wrappy, treeverse, @npmcli/eslint-config, @npmcli/template-oss, minify-registry-metadata, @npmcli/disparity-colors, @npmcli/ci-detect, mute-stream, ini, npm-audit-report, npm-user-validate \ No newline at end of file + - @npmcli/docs, @npmcli/installed-package-contents, @npmcli/map-workspaces, cacache, npm-pick-manifest, @npmcli/run-script, read-package-json, @npmcli/query, readdir-scoped-modules, promzard + - @npmcli/fs, npm-bundled, read-package-json-fast, unique-filename, @npmcli/promise-spawn, npm-install-checks, npm-package-arg, npm-packlist, normalize-package-data, @npmcli/package-json, bin-links, nopt, npmlog, parse-conflict-json, dezalgo, read + - semver, ignore-walk, @npmcli/eslint-config, @npmcli/template-oss, npm-normalize-package-bin, @npmcli/name-from-folder, json-parse-even-better-errors, @npmcli/move-file, fs-minipass, infer-owner, ssri, unique-slug, hosted-git-info, proc-log, validate-npm-package-name, @npmcli/node-gyp, minipass-fetch, cmd-shim, read-cmd-shim, write-file-atomic, abbrev, are-we-there-yet, gauge, wrappy, treeverse, minify-registry-metadata, @npmcli/disparity-colors, @npmcli/ci-detect, mute-stream, ini, npm-audit-report, npm-user-validate \ No newline at end of file diff --git a/Makefile b/Makefile index 5f66ee7174f16..997a095067c28 100644 --- a/Makefile +++ b/Makefile @@ -3,94 +3,9 @@ SHELL = bash PUBLISHTAG = $(shell node scripts/publish-tag.js) -# these docs have the @VERSION@ tag in them, so they have to be rebuilt -# whenever the package.json is touched, in case the version changed. -version_mandocs = $(shell grep -rl '@VERSION@' docs/content \ - |sed 's|.md|.1|g' \ - |sed 's|docs/content/commands/|man/man1/|g' ) - -cli_mandocs = $(shell find docs/content/commands -name '*.md' \ - |sed 's|.md|.1|g' \ - |sed 's|docs/content/commands/|man/man1/|g' ) - -files_mandocs = $(shell find docs/content/configuring-npm -name '*.md' \ - |sed 's|.md|.5|g' \ - |sed 's|docs/content/configuring-npm/|man/man5/|g' ) - -misc_mandocs = $(shell find docs/content/using-npm -name '*.md' \ - |sed 's|.md|.7|g' \ - |sed 's|docs/content/using-npm/|man/man7/|g' ) - -mandocs = $(cli_mandocs) $(files_mandocs) $(misc_mandocs) - -markdown_docs = $(shell for file in $(find lib/commands -name '*.js'); do echo docs/content/commands/npm-$(basename $file .js).md; done) - -all: docs - -docs: mandocs htmldocs $(markdown_docs) - -# don't regenerate the snapshot if we're generating -# snapshots, since presumably we just did that. -mandocs: deps $(mandocs) - @ ! [ "$${npm_lifecycle_event}" = "snap" ] && \ - ! [ "$${npm_lifecycle_event}" = "postsnap" ] && \ - TAP_SNAPSHOT=1 node test/lib/utils/config/definitions.js || true - -$(version_mandocs): package.json - -htmldocs: deps - node bin/npm-cli.js rebuild cmark-gfm - node docs/bin/dockhand.js - -clean: docsclean gitclean - -docsclean: - rm -rf man - deps: node bin/npm-cli.js run resetdeps -## targets for man files, these are encouraged to be only built by running `make docs` or `make mandocs` -man/man1/%.1: docs/content/commands/%.md docs/bin/docs-build.js - @[ -d man/man1 ] || mkdir -p man/man1 - node docs/bin/docs-build.js $< $@ - -man/man5/npm-json.5: man/man5/package.json.5 - cp $< $@ - -man/man5/npm-global.5: man/man5/folders.5 - cp $< $@ - -man/man5/%.5: docs/content/configuring-npm/%.md docs/bin/docs-build.js - @[ -d man/man5 ] || mkdir -p man/man5 - node docs/bin/docs-build.js $< $@ - -man/man7/%.7: docs/content/using-npm/%.md docs/bin/docs-build.js - @[ -d man/man7 ] || mkdir -p man/man7 - node docs/bin/docs-build.js $< $@ - -# Any time the config definitions description changes, automatically -# update the documentation to account for it -docs/content/using-npm/config.md: docs/bin/config-doc.js lib/utils/config/*.js - node docs/bin/config-doc.js - -mddocs: docs/bin/config-doc-command.js lib/utils/config/*.js lib/utils/cmd-list.js - @for file in $(shell find docs/content/commands -name 'npm-*.md'); do \ - cmdname=$$(basename $$file .md) ;\ - cmdname=$${cmdname##npm-} ;\ - echo node docs/bin/config-doc-command.js $${file} lib/commands/$${cmdname}.js ;\ - node docs/bin/config-doc-command.js $${file} lib/commands/$${cmdname}.js ;\ - done - -docs/content/commands/npm-%.md: lib/commands/%.js - node docs/bin/config-doc-command.js $@ $< - -freshdocs: - touch lib/utils/config/definitions.js - touch docs/bin/*.js - make docs - make mddocs - lint-all: deps node bin/npm-cli.js run lint-all @@ -113,10 +28,10 @@ prune: deps node bin/npm-cli.js prune --omit=dev --no-save --no-audit --no-fund node scripts/git-dirty.js -publish: gitclean ls-ok link docs lint-all test-all prune +publish: gitclean ls-ok link lint-all test-all prune node bin/npm-cli.js publish --tag=$(PUBLISHTAG) -release: gitclean ls-ok docs prune +release: gitclean ls-ok prune @bash scripts/release.sh -.PHONY: all latest install dev link docs mddocs clean uninstall lint-all test-all man docsclean release ls-ok deps prune freshdocs +.PHONY: link gitclean uninstall lint-all test-all release ls-ok deps prune diff --git a/docs/.gitignore b/docs/.gitignore index c09c2f4a26d85..79af2bfcaa4d8 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -10,12 +10,10 @@ !/.gitignore !/bin/ !/CHANGELOG* -!/content/ !/docs/ !/lib/ !/LICENSE* !/map.js -!/nav.yml !/package.json !/README* !/scripts/ diff --git a/docs/bin/build.js b/docs/bin/build.js new file mode 100644 index 0000000000000..80ce0a63490ff --- /dev/null +++ b/docs/bin/build.js @@ -0,0 +1,12 @@ +const run = require('../lib/build.js') +const { paths } = require('../lib/index') + +run({ + verify: true, + ...paths, +}) + .then((res) => console.log(`Wrote ${res.length} files`)) + .catch((err) => { + process.exitCode = 1 + console.error(err) + }) diff --git a/docs/bin/config-doc-command.js b/docs/bin/config-doc-command.js deleted file mode 100644 index f55213cdcfd6d..0000000000000 --- a/docs/bin/config-doc-command.js +++ /dev/null @@ -1,142 +0,0 @@ -const fs = require('fs').promises -const { resolve } = require('path') -const { definitions, aliases } = require('../lib/npm.js') - -const describeAll = (content) => - content.map(name => definitions[name].describe()).join( - '\n\n\n' + - '\n\n' - ) - -const describeUsage = ({ usage, configDoc, commandFile }) => { - const synopsis = [] - - // Grab the command name from the *.md filename - // NOTE: We cannot use the name property command file because in the case of - // `npx` the file being used is `lib/commands/exec.js` - const commandName = configDoc.split('/').pop().split('.')[0].replace('npm-', '') - synopsis.push('\n```bash') - - if (commandName) { - // special case for `npx`: - // `npx` is not technically a command in and of itself, - // so it just needs the usage and parameters of npm exec, and none of the aliases - if (commandName === 'npx') { - synopsis.push(usage.map(usageInfo => `npx ${usageInfo}`).join('\n')) - } else { - const baseCommand = `npm ${commandName}` - if (!usage) { - synopsis.push(baseCommand) - } else { - synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n')) - } - - const cmdAliases = Object.keys(aliases).reduce((p, c) => { - if (aliases[c] === commandName) { - p.push(c) - } - return p - }, []) - - if (cmdAliases.length === 1) { - synopsis.push('') - synopsis.push(`alias: ${cmdAliases[0]}`) - } else if (cmdAliases.length > 1) { - synopsis.push('') - synopsis.push(`aliases: ${cmdAliases.join(', ')}`) - } - } - } else { - console.error(`could not determine command name from ${commandFile}`) - } - - synopsis.push('```') - return synopsis.join('\n') -} - -const addBetweenTags = ( - doc, - startTag, - endTag, - body, - sourceFilepath = 'lib/utils/config/definitions.js') => { - const startSplit = doc.split(startTag) - - if (startSplit.length !== 2) { - throw new Error('Did not find exactly one start tag') - } - - const endSplit = startSplit[1].split(endTag) - if (endSplit.length !== 2) { - throw new Error('Did not find exactly one end tag') - } - - return [ - startSplit[0], - startTag, - '\n\n' + - '\n', - body, - '\n\n\n' + - '', - '\n\n', - endTag, - endSplit[1], - ].join('') -} - -const TAGS = { - CONFIG: { - START: '', - END: '', - }, - USAGE: { - START: '', - END: '', - }, -} - -const addDescriptions = ({ doc, params }) => - addBetweenTags(doc, TAGS.CONFIG.START, TAGS.CONFIG.END, describeAll(params)) - -const addUsageDescriptions = ({ doc, usage, configDoc, commandFile }) => - addBetweenTags(doc, TAGS.USAGE.START, TAGS.USAGE.END, - describeUsage({ usage, configDoc, commandFile }), - commandFile - ) - -const run = async (configDoc, commandFile) => { - try { - // Note: commands without params skip this whole process. - const { params, usage } = require(resolve(commandFile)) - - // always write SOMETHING so that Make sees the file is up to date. - const doc = await fs.readFile(configDoc, 'utf8') - const hasTag = doc.includes(TAGS.CONFIG.START) - const hasUsageTag = doc.includes(TAGS.USAGE.START) - - if (params && params.length) { - let newDoc = hasTag ? addDescriptions({ doc, params }) : doc - newDoc = hasUsageTag - ? addUsageDescriptions({ doc: newDoc, usage, configDoc, commandFile }) - : newDoc - - if (!hasTag) { - console.error('WARNING: did not find config description section', configDoc) - } - - if ((usage && usage.length) && !hasUsageTag) { - console.error('WARNING: did not find usage description section', configDoc) - } - await fs.writeFile(configDoc, newDoc) - } - } catch (err) { - console.error(`WARNING: file cannot be open: ${configDoc}`) - throw err - } -} - -run(...process.argv.slice(2)).catch((err) => { - process.exitCode = 1 - console.error(err) -}) diff --git a/docs/bin/config-doc.js b/docs/bin/config-doc.js deleted file mode 100644 index 1aa96e53cbb43..0000000000000 --- a/docs/bin/config-doc.js +++ /dev/null @@ -1,63 +0,0 @@ -const fs = require('fs').promises -const { resolve, relative } = require('path') -const { shorthands, describeAll } = require('../lib/npm.js') - -const addBetweenTags = (doc, startTag, endTag, body) => { - const startSplit = doc.split(startTag) - if (startSplit.length !== 2) { - throw new Error('Did not find exactly one start tag') - } - - const endSplit = startSplit[1].split(endTag) - if (endSplit.length !== 2) { - throw new Error('Did not find exactly one end tag') - } - - return [ - startSplit[0], - startTag, - '\n\n' + - '\n', - body, - '\n\n\n' + - '\n', - endTag, - endSplit[1], - ].join('') -} - -const addDescriptions = doc => { - const startTag = '' - const endTag = '' - return addBetweenTags(doc, startTag, endTag, describeAll()) -} - -const addShorthands = doc => { - const startTag = '' - const endTag = '' - const body = Object.entries(shorthands) - .sort(([shorta, expansiona], [shortb, expansionb]) => { - // sort by what they're short FOR - return expansiona.join(' ').localeCompare(expansionb.join(' '), 'en') || - shorta.localeCompare(shortb, 'en') - }) - .map(([short, expansion]) => { - const dash = short.length === 1 ? '-' : '--' - return `* \`${dash}${short}\`: \`${expansion.join(' ')}\`` - }).join('\n') - return addBetweenTags(doc, startTag, endTag, body) -} - -const run = async (dir) => { - const configDoc = resolve(dir, '../content/using-npm/config.md') - const doc = await fs.readFile(configDoc, 'utf8') - - await fs.writeFile(configDoc, addDescriptions(addShorthands(doc))) - - return `updated ${relative(process.cwd(), configDoc)}` -} - -run(__dirname).then(console.log).catch((err) => { - process.exitCode = 1 - console.error(err) -}) diff --git a/docs/bin/dockhand.js b/docs/bin/dockhand.js deleted file mode 100644 index 56160136eed6f..0000000000000 --- a/docs/bin/dockhand.js +++ /dev/null @@ -1,322 +0,0 @@ -const path = require('path') -const fs = require('fs') -const yaml = require('yaml') -const cmark = require('cmark-gfm') -const mdx = require('@mdx-js/mdx') -const mkdirp = require('mkdirp') -const jsdom = require('jsdom') -const { version: VERSION } = require('../lib/npm.js') - -function ensureNavigationComplete (navPaths, fsPaths) { - const unmatchedNav = {} - const unmatchedFs = {} - - for (const navPath of navPaths) { - unmatchedNav[navPath] = true - } - - for (let fsPath of fsPaths) { - fsPath = path.sep + fsPath.replace(/\.md$/, '') - fsPath = fsPath.split(path.sep).join(path.posix.sep) - - if (unmatchedNav[fsPath]) { - delete unmatchedNav[fsPath] - } else { - unmatchedFs[fsPath] = true - } - } - - const toKeys = (v) => Object.keys(v).sort().map((p) => p.split(path.posix.sep).join(path.sep)) - const missingNav = toKeys(unmatchedNav) - const missingFs = toKeys(unmatchedFs) - - if (missingNav.length > 0 || missingFs.length > 0) { - let message = 'Error: documentation navigation (nav.yml) does not match filesystem.\n' - - if (missingNav.length > 0) { - message += '\nThe following path(s) exist on disk but are not present in nav.yml:\n\n' - - for (const n of missingNav) { - message += ` ${n}\n` - } - } - - if (missingNav.length > 0 && missingFs.length > 0) { - message += '\nThe following path(s) exist in nav.yml but are not present on disk:\n\n' - - for (const m of missingFs) { - message += ` ${m}\n` - } - } - - message += '\nUpdate nav.yml to ensure that all files are listed in the appropriate place.' - - return message - } -} - -function getNavigationPaths (entries) { - const paths = [] - - for (const entry of entries) { - if (entry.children) { - paths.push(...getNavigationPaths(entry.children)) - } else { - paths.push(entry.url) - } - } - - return paths -} - -async function renderFilesystemPaths ({ input, output, ...opts }, dirRelative = null) { - const paths = [] - - const dirPath = dirRelative ? path.join(input, dirRelative) : input - const children = fs.readdirSync(dirPath) - - for (const childFilename of children) { - const childRelative = dirRelative ? path.join(dirRelative, childFilename) : childFilename - const childPath = path.join(input, childRelative) - - if (fs.lstatSync(childPath).isDirectory()) { - paths.push(...(await renderFilesystemPaths({ input, output, ...opts }, childRelative))) - } else { - await renderFile(input, output, childRelative, opts) - paths.push(childRelative) - } - } - - return paths -} - -async function renderFile (root, outputRoot, childPath, { template, config }) { - const inputPath = path.join(root, childPath) - - if (!inputPath.match(/\.md$/)) { - console.error(`warning: unknown file type ${inputPath}, ignored`) - return - } - - const outputPath = path.join(outputRoot, childPath.replace(/\.md$/, '.html')) - - let md = fs.readFileSync(inputPath).toString() - let frontmatter = {} - - // Take the leading frontmatter out of the markdown - md = md.replace(/^---\n([\s\S]+)\n---\n/, (header, fm) => { - frontmatter = yaml.parse(fm, 'utf8') - return '' - }) - - // Replace any tokens in the source - md = md.replace(/@VERSION@/, VERSION) - - // Render the markdown into an HTML snippet using a GFM renderer. - const content = cmark.renderHtmlSync(md, { - smart: false, - githubPreLang: true, - strikethroughDoubleTilde: true, - unsafe: false, - extensions: { - table: true, - strikethrough: true, - tagfilter: true, - autolink: true, - }, - }) - - // Test that mdx can parse this markdown file. We don't actually - // use the output, it's just to ensure that the upstream docs - // site (docs.npmjs.com) can parse it when this file gets there. - try { - await mdx(md, { skipExport: true }) - } catch (error) { - throw new MarkdownError(childPath, error) - } - - // Inject this data into the template, using a mustache-like - // replacement scheme. - const html = template.replace(/{{\s*([\w.]+)\s*}}/g, (token, key) => { - switch (key) { - case 'content': - return `
${content}
` - case 'path': - return childPath - case 'url_path': - return encodeURI(childPath) - - case 'toc': - return '
' - - case 'title': - case 'section': - case 'description': - return frontmatter[key] - - case 'config.github_repo': - case 'config.github_branch': - case 'config.github_path': - return config[key.replace(/^config\./, '')] - - default: - console.error(`warning: unknown token '${token}' in ${inputPath}`) - return '' - } - }) - - const dom = new jsdom.JSDOM(html) - const document = dom.window.document - - // Rewrite relative URLs in links and image sources to be relative to - // this file; this is for supporting `file://` links. HTML pages need - // suffix appended. - const links = [ - { tag: 'a', attr: 'href', suffix: '.html' }, - { tag: 'img', attr: 'src' }, - ] - - for (const linktype of links) { - for (const tag of document.querySelectorAll(linktype.tag)) { - let url = tag.getAttribute(linktype.attr) - - if (url.startsWith('/')) { - const childDepth = childPath.split('/').length - 1 - const prefix = childDepth > 0 ? '../'.repeat(childDepth) : './' - - url = url.replace(/^\//, prefix) - - if (linktype.suffix) { - url += linktype.suffix - } - - tag.setAttribute(linktype.attr, url) - } - } - } - - // Give headers a unique id so that they can be linked within the doc - const headerIds = [] - for (const header of document.querySelectorAll('h1, h2, h3, h4, h5, h6')) { - if (header.getAttribute('id')) { - headerIds.push(header.getAttribute('id')) - continue - } - - const headerText = header.textContent - .replace(/[A-Z]/g, x => x.toLowerCase()) - .replace(/ /g, '-') - .replace(/[^a-z0-9-]/g, '') - let headerId = headerText - let headerIncrement = 1 - - while (document.getElementById(headerId) !== null) { - headerId = headerText + ++headerIncrement - } - - headerIds.push(headerId) - header.setAttribute('id', headerId) - } - - // Walk the dom and build a table of contents - const toc = document.getElementById('_table_of_contents') - - if (toc) { - toc.appendChild(generateTableOfContents(document)) - } - - // Write the final output - const output = dom.serialize() - - mkdirp.sync(path.dirname(outputPath)) - fs.writeFileSync(outputPath, output) -} - -function generateTableOfContents (document) { - const headers = [] - walkHeaders(document.getElementById('_content'), headers) - - // The nesting depth of headers are not necessarily the header level. - // (eg, h1 > h3 > h5 is a depth of three even though there's an h5.) - const hierarchy = [] - for (const header of headers) { - const level = headerLevel(header) - - while (hierarchy.length && hierarchy[hierarchy.length - 1].headerLevel > level) { - hierarchy.pop() - } - - if (!hierarchy.length || hierarchy[hierarchy.length - 1].headerLevel < level) { - const newList = document.createElement('ul') - newList.headerLevel = level - - if (hierarchy.length) { - hierarchy[hierarchy.length - 1].appendChild(newList) - } - - hierarchy.push(newList) - } - - const element = document.createElement('li') - - const link = document.createElement('a') - link.setAttribute('href', `#${header.getAttribute('id')}`) - link.innerHTML = header.innerHTML - element.appendChild(link) - - const list = hierarchy[hierarchy.length - 1] - list.appendChild(element) - } - - return hierarchy[0] -} - -function walkHeaders (element, headers) { - for (const child of element.childNodes) { - if (headerLevel(child)) { - headers.push(child) - } - - walkHeaders(child, headers) - } -} - -function headerLevel (node) { - const level = node.tagName ? node.tagName.match(/^[Hh]([123456])$/) : null - return level ? level[1] : 0 -} - -class MarkdownError extends Error { - constructor (file, inner) { - super(`failed to parse ${file}`) - this.file = file - this.inner = inner - } -} - -const run = async function (rootDir) { - const dir = (...p) => path.join(rootDir, '..', ...p) - - const config = require(dir('lib', 'config.json')) - const template = fs.readFileSync(dir('lib', 'template.html'), 'utf-8') - const nav = yaml.parse(fs.readFileSync(dir('nav.yml'), 'utf-8')) - - const navPaths = getNavigationPaths(nav) - const fsPaths = await renderFilesystemPaths({ - input: dir('content'), - output: dir('output'), - config, - template, - }) - - const navErrors = ensureNavigationComplete(navPaths, fsPaths) - if (navErrors) { - console.error(navErrors) - throw new Error('Nav Errors') - } -} - -run(__dirname).catch((err) => { - process.exitCode = 1 - console.error(err) -}) diff --git a/docs/bin/docs-build.js b/docs/bin/docs-build.js deleted file mode 100644 index 61343bfa45729..0000000000000 --- a/docs/bin/docs-build.js +++ /dev/null @@ -1,39 +0,0 @@ -const fs = require('fs').promises -const marked = require('marked-man') -const { version: VERSION } = require('../lib/npm.js') - -function frontmatter (_, p1) { - const fm = {} - - p1.split(/\r?\n/).forEach((kv) => { - const result = kv.match(/^([^\s:]+):\s*(.*)/) - if (result) { - fm[result[1]] = result[2] - } - }) - - return `# ${fm.title}(${fm.section}) - ${fm.description}` -} - -function replacer (_, p1) { - return 'npm help ' + p1.replace(/npm /, '') -} - -const run = async (src, dest = src) => { - const data = await fs.readFile(src, 'utf8') - - const result = data.replace(/@VERSION@/g, VERSION) - .replace(/^$/gm, '') - .replace(/^---\n([\s\S]+\n)---/, frontmatter) - .replace(/\[([^\]]+)\]\(\/commands\/([^)]+)\)/g, replacer) - .replace(/\[([^\]]+)\]\(\/configuring-npm\/([^)]+)\)/g, replacer) - .replace(/\[([^\]]+)\]\(\/using-npm\/([^)]+)\)/g, replacer) - .trim() - - await fs.writeFile(dest, marked(result), 'utf8') -} - -run(...process.argv.slice(2)).catch((err) => { - process.exitCode = 1 - console.error(err) -}) diff --git a/docs/content/commands/npm-adduser.md b/docs/content/commands/npm-adduser.md deleted file mode 100644 index 710060f838ff7..0000000000000 --- a/docs/content/commands/npm-adduser.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: npm-adduser -section: 1 -description: Add a registry user account ---- - -### Synopsis - - - - - -```bash -npm adduser - -alias: add-user -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Create a new user in the specified registry, and save the credentials to -the `.npmrc` file. If no registry is specified, the default registry -will be used (see [`registry`](/using-npm/registry)). - -When using `legacy` for your `auth-type`, the username, password, and -email are read in from prompts. - -### Configuration - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `scope` - -* Default: the scope of the current project, if any, or "" -* Type: String - -Associate an operation with a scope for a scoped registry. - -Useful when logging in to or out of a private registry: - -``` -# log in, linking the scope to the custom registry -npm login --scope=@mycorp --registry=https://registry.mycorp.com - -# log out, removing the link and the auth token -npm logout --scope=@mycorp -``` - -This will cause `@mycorp` to be mapped to the registry for future -installation of packages specified according to the pattern -`@mycorp/package`. - -This will also cause `npm init` to create a scoped package. - -``` -# accept all defaults, and create a package named "@foo/whatever", -# instead of just named "whatever" -npm init --scope=@foo --yes -``` - - - - - -#### `auth-type` - -* Default: "web" -* Type: "legacy" or "web" - -What authentication strategy to use with `login`. - - - - - - -### See Also - -* [npm registry](/using-npm/registry) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [npm owner](/commands/npm-owner) -* [npm whoami](/commands/npm-whoami) -* [npm token](/commands/npm-token) -* [npm profile](/commands/npm-profile) diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md deleted file mode 100644 index 94b72cfd5c81c..0000000000000 --- a/docs/content/commands/npm-bin.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: npm-bin -section: 1 -description: Display npm bin folder ---- - -### Synopsis - - - - - -```bash -npm bin -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Print the folder where npm will install executables. - -### Configuration - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - - - -### See Also - -* [npm prefix](/commands/npm-prefix) -* [npm root](/commands/npm-root) -* [npm folders](/configuring-npm/folders) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-bugs.md b/docs/content/commands/npm-bugs.md deleted file mode 100644 index af52548389c92..0000000000000 --- a/docs/content/commands/npm-bugs.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: npm-bugs -section: 1 -description: Report bugs for a package in a web browser ---- - -### Synopsis - - - - - -```bash -npm bugs [ [ ...]] - -alias: issues -``` - - - - - - -### Description - -This command tries to guess at the likely location of a package's bug -tracker URL or the `mailto` URL of the support email, and then tries to -open it using the [`--browser` config](/using-npm/config#browser) param. If no -package name is provided, it will search for a `package.json` in the current -folder and use the `name` property. - -### Configuration - - - - -#### `browser` - -* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: null, Boolean, or String - -The browser that is called by npm commands to open websites. - -Set to `false` to suppress browser behavior and instead print urls to -terminal. - -Set to `true` to use default system URL opener. - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - - -### See Also - -* [npm docs](/commands/npm-docs) -* [npm view](/commands/npm-view) -* [npm publish](/commands/npm-publish) -* [npm registry](/using-npm/registry) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [package.json](/configuring-npm/package-json) diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md deleted file mode 100644 index fee305618cca3..0000000000000 --- a/docs/content/commands/npm-ci.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -title: npm-ci -section: 1 -description: Clean install a project ---- - -### Synopsis - - - - - -```bash -npm ci - -aliases: clean-install, ic, install-clean, isntall-clean -``` - - - - - - -### Description - -This command is similar to [`npm install`](/commands/npm-install), except -it's meant to be used in automated environments such as test platforms, -continuous integration, and deployment -- or any situation where you want -to make sure you're doing a clean install of your dependencies. - -The main differences between using `npm install` and `npm ci` are: - -* The project **must** have an existing `package-lock.json` or - `npm-shrinkwrap.json`. -* If dependencies in the package lock do not match those in `package.json`, - `npm ci` will exit with an error, instead of updating the package lock. -* `npm ci` can only install entire projects at a time: individual - dependencies cannot be added with this command. -* If a `node_modules` is already present, it will be automatically removed - before `npm ci` begins its install. -* It will never write to `package.json` or any of the package-locks: - installs are essentially frozen. - -NOTE: If you create your `package-lock.json` file by running `npm install` -with flags that can affect the shape of your dependency tree, such as -`--legacy-peer-deps` or `--install-links`, you _must_ provide the same -flags to `npm ci` or you are likely to encounter errors. An easy way to do -this is to run, for example, -`npm config set legacy-peer-deps=true --location=project` and commit the -`.npmrc` file to your repo. - -### Example - -Make sure you have a package-lock and an up-to-date install: - -```bash -$ cd ./my/npm/project -$ npm install -added 154 packages in 10s -$ ls | grep package-lock -``` - -Run `npm ci` in that project - -```bash -$ npm ci -added 154 packages in 5s -``` - -Configure Travis CI to build using `npm ci` instead of `npm install`: - -```bash -# .travis.yml -install: -- npm ci -# keep the npm cache around to speed up installs -cache: - directories: - - "$HOME/.npm" -``` - -### Configuration - - - - -#### `save` - -* Default: `true` unless when using `npm update` where it defaults to `false` -* Type: Boolean - -Save installed packages to a `package.json` file as dependencies. - -When used with the `npm rm` command, removes the dependency from -`package.json`. - -Will also prevent writing to `package-lock.json` if set to `false`. - - - - -#### `save-exact` - -* Default: false -* Type: Boolean - -Dependencies saved to package.json will be configured with an exact version -rather than using npm's default semver range operator. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `global-style` - -* Default: false -* Type: Boolean - -Causes npm to install the package into your local `node_modules` folder with -the same layout it uses with the global `node_modules` folder. Only your -direct dependencies will show in `node_modules` and everything they depend -on will be flattened in their `node_modules` folders. This obviously will -eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` -will be preferred. - - - - -#### `legacy-bundling` - -* Default: false -* Type: Boolean - -Causes npm to install the package such that versions of npm prior to 1.4, -such as the one included with node 0.8, can install the package. This -eliminates all automatic deduping. If used with `global-style` this option -will be preferred. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `strict-peer-deps` - -* Default: false -* Type: Boolean - -If set to `true`, and `--legacy-peer-deps` is not set, then _any_ -conflicting `peerDependencies` will be treated as an install failure, even -if npm could reasonably guess the appropriate resolution based on non-peer -dependency relationships. - -By default, conflicting `peerDependencies` deep in the dependency graph will -be resolved using the nearest non-peer dependency specification, even if -doing so will result in some packages receiving a peer dependency outside -the range set in their package's `peerDependencies` object. - -When such and override is performed, a warning is printed, explaining the -conflict and the packages involved. If `--strict-peer-deps` is set, then -this warning is treated as a failure. - - - - -#### `package-lock` - -* Default: true -* Type: Boolean - -If set to false, then ignore `package-lock.json` files when installing. This -will also prevent _writing_ `package-lock.json` if `save` is true. - -This configuration does not affect `npm ci`. - - - - -#### `foreground-scripts` - -* Default: false -* Type: Boolean - -Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) -scripts for installed packages in the foreground process, sharing standard -input, output, and error with the main npm process. - -Note that this will generally make installs run slower, and be much noisier, -but can be useful for debugging. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `audit` - -* Default: true -* Type: Boolean - -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `fund` - -* Default: true -* Type: Boolean - -When "true" displays the message at the end of each `npm install` -acknowledging the number of dependencies looking for funding. See [`npm -fund`](/commands/npm-fund) for details. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [npm install](/commands/npm-install) -* [package-lock.json](/configuring-npm/package-lock-json) diff --git a/docs/content/commands/npm-config.md b/docs/content/commands/npm-config.md deleted file mode 100644 index 6e0c0b682d724..0000000000000 --- a/docs/content/commands/npm-config.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: npm-config -section: 1 -description: Manage the npm configuration files ---- - -### Synopsis - - - - - -```bash -npm config set = [= ...] -npm config get [ [ ...]] -npm config delete [ ...] -npm config list [--json] -npm config edit - -alias: c -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -npm gets its config settings from the command line, environment -variables, `npmrc` files, and in some cases, the `package.json` file. - -See [npmrc](/configuring-npm/npmrc) for more information about the npmrc -files. - -See [config](/using-npm/config) for a more thorough explanation of the -mechanisms involved, and a full list of config options available. - -The `npm config` command can be used to update and edit the contents -of the user and global npmrc files. - -### Sub-commands - -Config supports the following sub-commands: - -#### set - -```bash -npm config set key=value [key=value...] -npm set key=value [key=value...] -``` - -Sets each of the config keys to the value provided. - -If value is omitted, then it sets it to an empty string. - -Note: for backwards compatibility, `npm config set key value` is supported -as an alias for `npm config set key=value`. - -#### get - -```bash -npm config get [key ...] -npm get [key ...] -``` - -Echo the config value(s) to stdout. - -If multiple keys are provided, then the values will be prefixed with the -key names. - -If no keys are provided, then this command behaves the same as `npm config -list`. - -#### list - -```bash -npm config list -``` - -Show all the config settings. Use `-l` to also show defaults. Use `--json` -to show the settings in json format. - -#### delete - -```bash -npm config delete key [key ...] -``` - -Deletes the specified keys from all configuration files. - -#### edit - -```bash -npm config edit -``` - -Opens the config file in an editor. Use the `--global` flag to edit the -global config. - -### Configuration - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `editor` - -* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on - Windows, or 'vim' on Unix systems -* Type: String - -The command to run for `npm edit` and `npm config edit`. - - - - -#### `location` - -* Default: "user" unless `--global` is passed, which will also set this value - to "global" -* Type: "global", "user", or "project" - -When passed to `npm config` this refers to which config file to use. - -When set to "global" mode, packages are installed into the `prefix` folder -instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `long` - -* Default: false -* Type: Boolean - -Show extended information in `ls`, `search`, and `help-search`. - - - - - - -### See Also - -* [npm folders](/configuring-npm/folders) -* [npm config](/commands/npm-config) -* [package.json](/configuring-npm/package-json) -* [npmrc](/configuring-npm/npmrc) -* [npm](/commands/npm) diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md deleted file mode 100644 index 4a7e0ab6b9851..0000000000000 --- a/docs/content/commands/npm-dedupe.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: npm-dedupe -section: 1 -description: Reduce duplication in the package tree ---- - -### Synopsis - - - - - -```bash -npm dedupe - -alias: ddp -``` - - - - - - -### Description - -Searches the local package tree and attempts to simplify the overall -structure by moving dependencies further up the tree, where they can -be more effectively shared by multiple dependent packages. - -For example, consider this dependency graph: - -``` -a -+-- b <-- depends on c@1.0.x -| `-- c@1.0.3 -`-- d <-- depends on c@~1.0.9 - `-- c@1.0.10 -``` - -In this case, `npm dedupe` will transform the tree to: - -```bash -a -+-- b -+-- d -`-- c@1.0.10 -``` - -Because of the hierarchical nature of node's module lookup, b and d -will both get their dependency met by the single c package at the root -level of the tree. - -In some cases, you may have a dependency graph like this: - -``` -a -+-- b <-- depends on c@1.0.x -+-- c@1.0.3 -`-- d <-- depends on c@1.x - `-- c@1.9.9 -``` - -During the installation process, the `c@1.0.3` dependency for `b` was -placed in the root of the tree. Though `d`'s dependency on `c@1.x` could -have been satisfied by `c@1.0.3`, the newer `c@1.9.0` dependency was used, -because npm favors updates by default, even when doing so causes -duplication. - -Running `npm dedupe` will cause npm to note the duplication and -re-evaluate, deleting the nested `c` module, because the one in the root is -sufficient. - -To prefer deduplication over novelty during the installation process, run -`npm install --prefer-dedupe` or `npm config set prefer-dedupe true`. - -Arguments are ignored. Dedupe always acts on the entire tree. - -Note that this operation transforms the dependency tree, but will never -result in new modules being installed. - -Using `npm find-dupes` will run the command in `--dry-run` mode. - -Note: `npm dedupe` will never update the semver values of direct -dependencies in your project `package.json`, if you want to update -values in `package.json` you can run: `npm update --save` instead. - -### Configuration - - - - -#### `global-style` - -* Default: false -* Type: Boolean - -Causes npm to install the package into your local `node_modules` folder with -the same layout it uses with the global `node_modules` folder. Only your -direct dependencies will show in `node_modules` and everything they depend -on will be flattened in their `node_modules` folders. This obviously will -eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` -will be preferred. - - - - -#### `legacy-bundling` - -* Default: false -* Type: Boolean - -Causes npm to install the package such that versions of npm prior to 1.4, -such as the one included with node 0.8, can install the package. This -eliminates all automatic deduping. If used with `global-style` this option -will be preferred. - - - - -#### `strict-peer-deps` - -* Default: false -* Type: Boolean - -If set to `true`, and `--legacy-peer-deps` is not set, then _any_ -conflicting `peerDependencies` will be treated as an install failure, even -if npm could reasonably guess the appropriate resolution based on non-peer -dependency relationships. - -By default, conflicting `peerDependencies` deep in the dependency graph will -be resolved using the nearest non-peer dependency specification, even if -doing so will result in some packages receiving a peer dependency outside -the range set in their package's `peerDependencies` object. - -When such and override is performed, a warning is printed, explaining the -conflict and the packages involved. If `--strict-peer-deps` is set, then -this warning is treated as a failure. - - - - -#### `package-lock` - -* Default: true -* Type: Boolean - -If set to false, then ignore `package-lock.json` files when installing. This -will also prevent _writing_ `package-lock.json` if `save` is true. - -This configuration does not affect `npm ci`. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `audit` - -* Default: true -* Type: Boolean - -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `fund` - -* Default: true -* Type: Boolean - -When "true" displays the message at the end of each `npm install` -acknowledging the number of dependencies looking for funding. See [`npm -fund`](/commands/npm-fund) for details. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [npm find-dupes](/commands/npm-find-dupes) -* [npm ls](/commands/npm-ls) -* [npm update](/commands/npm-update) -* [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-diff.md b/docs/content/commands/npm-diff.md deleted file mode 100644 index 7dcc8af7c3b4c..0000000000000 --- a/docs/content/commands/npm-diff.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: npm-diff -section: 1 -description: The registry diff command ---- - -### Synopsis - - - - - -```bash -npm diff [...] -``` - - - - - - -### Description - -Similar to its `git diff` counterpart, this command will print diff patches -of files for packages published to the npm registry. - -* `npm diff --diff= --diff=` - - Compares two package versions using their registry specifiers, e.g: - `npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0`. It's also possible to - compare across forks of any package, - e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0`. - - Any valid spec can be used, so that it's also possible to compare - directories or git repositories, - e.g: `npm diff --diff=pkg@latest --diff=./packages/pkg` - - Here's an example comparing two different versions of a package named - `abbrev` from the registry: - - ```bash - npm diff --diff=abbrev@1.1.0 --diff=abbrev@1.1.1 - ``` - - On success, output looks like: - - ```bash - diff --git a/package.json b/package.json - index v1.1.0..v1.1.1 100644 - --- a/package.json - +++ b/package.json - @@ -1,6 +1,6 @@ - { - "name": "abbrev", - - "version": "1.1.0", - + "version": "1.1.1", - "description": "Like ruby's abbrev module, but in js", - "author": "Isaac Z. Schlueter ", - "main": "abbrev.js", - ``` - - Given the flexible nature of npm specs, you can also target local - directories or git repos just like when using `npm install`: - - ```bash - npm diff --diff=/~https://github.com/npm/libnpmdiff --diff=./local-path - ``` - - In the example above we can compare the contents from the package installed - from the git repo at `github.com/npm/libnpmdiff` with the contents of the - `./local-path` that contains a valid package, such as a modified copy of - the original. - -* `npm diff` (in a package directory, no arguments): - - If the package is published to the registry, `npm diff` will fetch the - tarball version tagged as `latest` (this value can be configured using the - `tag` option) and proceed to compare the contents of files present in that - tarball, with the current files in your local file system. - - This workflow provides a handy way for package authors to see what - package-tracked files have been changed in comparison with the latest - published version of that package. - -* `npm diff --diff=` (in a package directory): - - When using a single package name (with no version or tag specifier) as an - argument, `npm diff` will work in a similar way to - [`npm-outdated`](npm-outdated) and reach for the registry to figure out - what current published version of the package named `` - will satisfy its dependent declared semver-range. Once that specific - version is known `npm diff` will print diff patches comparing the - current version of `` found in the local file system with - that specific version returned by the registry. - - Given a package named `abbrev` that is currently installed: - - ```bash - npm diff --diff=abbrev - ``` - - That will request from the registry its most up to date version and - will print a diff output comparing the currently installed version to this - newer one if the version numbers are not the same. - -* `npm diff --diff=` (in a package directory): - - Similar to using only a single package name, it's also possible to declare - a full registry specifier version if you wish to compare the local version - of an installed package with the specific version/tag/semver-range provided - in ``. - - An example: assuming `pkg@1.0.0` is installed in the current `node_modules` - folder, running: - - ```bash - npm diff --diff=pkg@2.0.0 - ``` - - It will effectively be an alias to - `npm diff --diff=pkg@1.0.0 --diff=pkg@2.0.0`. - -* `npm diff --diff= [--diff=]` (in a package directory): - - Using `npm diff` along with semver-valid version numbers is a shorthand - to compare different versions of the current package. - - It needs to be run from a package directory, such that for a package named - `pkg` running `npm diff --diff=1.0.0 --diff=1.0.1` is the same as running - `npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1`. - - If only a single argument `` is provided, then the current local - file system is going to be compared against that version. - - Here's an example comparing two specific versions (published to the - configured registry) of the current project directory: - - ```bash - npm diff --diff=1.0.0 --diff=1.1.0 - ``` - -Note that tag names are not valid `--diff` argument values, if you wish to -compare to a published tag, you must use the `pkg@tagname` syntax. - -#### Filtering files - -It's possible to also specify positional arguments using file names or globs -pattern matching in order to limit the result of diff patches to only a subset -of files for a given package, e.g: - - ```bash - npm diff --diff=pkg@2 ./lib/ CHANGELOG.md - ``` - -In the example above the diff output is only going to print contents of files -located within the folder `./lib/` and changed lines of code within the -`CHANGELOG.md` file. - -### Configuration - - - - -#### `diff` - -* Default: -* Type: String (can be set multiple times) - -Define arguments to compare in `npm diff`. - - - - -#### `diff-name-only` - -* Default: false -* Type: Boolean - -Prints only filenames when using `npm diff`. - - - - -#### `diff-unified` - -* Default: 3 -* Type: Number - -The number of lines of context to print in `npm diff`. - - - - -#### `diff-ignore-all-space` - -* Default: false -* Type: Boolean - -Ignore whitespace when comparing lines in `npm diff`. - - - - -#### `diff-no-prefix` - -* Default: false -* Type: Boolean - -Do not show any source or destination prefix in `npm diff` output. - -Note: this causes `npm diff` to ignore the `--diff-src-prefix` and -`--diff-dst-prefix` configs. - - - - -#### `diff-src-prefix` - -* Default: "a/" -* Type: String - -Source prefix to be used in `npm diff` output. - - - - -#### `diff-dst-prefix` - -* Default: "b/" -* Type: String - -Destination prefix to be used in `npm diff` output. - - - - -#### `diff-text` - -* Default: false -* Type: Boolean - -Treat all files as text in `npm diff`. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `tag` - -* Default: "latest" -* Type: String - -If you ask npm to install a package and don't tell it a specific version, -then it will install the specified tag. - -Also the tag that is added to the package@version specified by the `npm tag` -command, if no explicit tag is given. - -When used by the `npm diff` command, this is the tag used to fetch the -tarball that will be compared with the local files by default. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - -## See Also - -* [npm outdated](/commands/npm-outdated) -* [npm install](/commands/npm-install) -* [npm config](/commands/npm-config) -* [npm registry](/using-npm/registry) diff --git a/docs/content/commands/npm-docs.md b/docs/content/commands/npm-docs.md deleted file mode 100644 index e48695ced005a..0000000000000 --- a/docs/content/commands/npm-docs.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: npm-docs -section: 1 -description: Open documentation for a package in a web browser ---- - -### Synopsis - - - - - -```bash -npm docs [ [ ...]] - -alias: home -``` - - - - - - -### Description - -This command tries to guess at the likely location of a package's -documentation URL, and then tries to open it using the -[`--browser` config](/using-npm/config#browser) param. You can pass multiple -package names at once. If no package name is provided, it will search for a -`package.json` in the current folder and use the `name` property. - -### Configuration - - - - -#### `browser` - -* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: null, Boolean, or String - -The browser that is called by npm commands to open websites. - -Set to `false` to suppress browser behavior and instead print urls to -terminal. - -Set to `true` to use default system URL opener. - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - - -### See Also - -* [npm view](/commands/npm-view) -* [npm publish](/commands/npm-publish) -* [npm registry](/using-npm/registry) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [package.json](/configuring-npm/package-json) diff --git a/docs/content/commands/npm-find-dupes.md b/docs/content/commands/npm-find-dupes.md deleted file mode 100644 index af41f5ccb14f2..0000000000000 --- a/docs/content/commands/npm-find-dupes.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: npm-find-dupes -section: 1 -description: Find duplication in the package tree ---- - -### Synopsis - - - - - -```bash -npm find-dupes -``` - - - - - - -### Description - -Runs `npm dedupe` in `--dry-run` mode, making npm only output the -duplications, without actually changing the package tree. - -### Configuration - - - - -#### `global-style` - -* Default: false -* Type: Boolean - -Causes npm to install the package into your local `node_modules` folder with -the same layout it uses with the global `node_modules` folder. Only your -direct dependencies will show in `node_modules` and everything they depend -on will be flattened in their `node_modules` folders. This obviously will -eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` -will be preferred. - - - - -#### `legacy-bundling` - -* Default: false -* Type: Boolean - -Causes npm to install the package such that versions of npm prior to 1.4, -such as the one included with node 0.8, can install the package. This -eliminates all automatic deduping. If used with `global-style` this option -will be preferred. - - - - -#### `strict-peer-deps` - -* Default: false -* Type: Boolean - -If set to `true`, and `--legacy-peer-deps` is not set, then _any_ -conflicting `peerDependencies` will be treated as an install failure, even -if npm could reasonably guess the appropriate resolution based on non-peer -dependency relationships. - -By default, conflicting `peerDependencies` deep in the dependency graph will -be resolved using the nearest non-peer dependency specification, even if -doing so will result in some packages receiving a peer dependency outside -the range set in their package's `peerDependencies` object. - -When such and override is performed, a warning is printed, explaining the -conflict and the packages involved. If `--strict-peer-deps` is set, then -this warning is treated as a failure. - - - - -#### `package-lock` - -* Default: true -* Type: Boolean - -If set to false, then ignore `package-lock.json` files when installing. This -will also prevent _writing_ `package-lock.json` if `save` is true. - -This configuration does not affect `npm ci`. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `audit` - -* Default: true -* Type: Boolean - -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `fund` - -* Default: true -* Type: Boolean - -When "true" displays the message at the end of each `npm install` -acknowledging the number of dependencies looking for funding. See [`npm -fund`](/commands/npm-fund) for details. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [npm dedupe](/commands/npm-dedupe) -* [npm ls](/commands/npm-ls) -* [npm update](/commands/npm-update) -* [npm install](/commands/npm-install) - diff --git a/docs/content/commands/npm-fund.md b/docs/content/commands/npm-fund.md deleted file mode 100644 index 53100f6716537..0000000000000 --- a/docs/content/commands/npm-fund.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: npm-fund -section: 1 -description: Retrieve funding information ---- - -### Synopsis - - - - - -```bash -npm fund [] -``` - - - - - - -### Description - -This command retrieves information on how to fund the dependencies of a -given project. If no package name is provided, it will list all -dependencies that are looking for funding in a tree structure, listing -the type of funding and the url to visit. If a package name is provided -then it tries to open its funding url using the -[`--browser` config](/using-npm/config#browser) param; if there are multiple -funding sources for the package, the user will be instructed to pass the -`--which` option to disambiguate. - -The list will avoid duplicated entries and will stack all packages that -share the same url as a single entry. Thus, the list does not have the -same shape of the output from `npm ls`. - -#### Example - -### Workspaces support - -It's possible to filter the results to only include a single workspace -and its dependencies using the -[`workspace` config](/using-npm/config#workspace) option. - -#### Example: - -Here's an example running `npm fund` in a project with a configured -workspace `a`: - -```bash -$ npm fund -test-workspaces-fund@1.0.0 -+-- https://example.com/a -| | `-- a@1.0.0 -| `-- https://example.com/maintainer -| `-- foo@1.0.0 -+-- https://example.com/npmcli-funding -| `-- @npmcli/test-funding -`-- https://example.com/org - `-- bar@2.0.0 -``` - -And here is an example of the expected result when filtering only by a -specific workspace `a` in the same project: - -```bash -$ npm fund -w a -test-workspaces-fund@1.0.0 -`-- https://example.com/a - | `-- a@1.0.0 - `-- https://example.com/maintainer - `-- foo@2.0.0 -``` - -### Configuration - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `browser` - -* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: null, Boolean, or String - -The browser that is called by npm commands to open websites. - -Set to `false` to suppress browser behavior and instead print urls to -terminal. - -Set to `true` to use default system URL opener. - - - - -#### `unicode` - -* Default: false on windows, true on mac/unix systems with a unicode locale, - as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables. -* Type: Boolean - -When set to true, npm uses unicode characters in the tree output. When -false, it uses ascii characters instead of unicode glyphs. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `which` - -* Default: null -* Type: null or Number - -If there are multiple funding sources, which 1-indexed source URL to open. - - - - - - -## See Also - -* [package spec](/using-npm/package-spec) -* [npm install](/commands/npm-install) -* [npm docs](/commands/npm-docs) -* [npm ls](/commands/npm-ls) -* [npm config](/commands/npm-config) -* [npm workspaces](/using-npm/workspaces) diff --git a/docs/content/commands/npm-help-search.md b/docs/content/commands/npm-help-search.md deleted file mode 100644 index 152f9f6bec16f..0000000000000 --- a/docs/content/commands/npm-help-search.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: npm-help-search -section: 1 -description: Search npm help documentation ---- - -### Synopsis - - - - - -```bash -npm help-search -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -This command will search the npm markdown documentation files for the terms -provided, and then list the results, sorted by relevance. - -If only one result is found, then it will show that help topic. - -If the argument to `npm help` is not a known help topic, then it will call -`help-search`. It is rarely if ever necessary to call this command -directly. - -### Configuration - - - - -#### `long` - -* Default: false -* Type: Boolean - -Show extended information in `ls`, `search`, and `help-search`. - - - - - - -### See Also - -* [npm](/commands/npm) -* [npm help](/commands/npm-help) diff --git a/docs/content/commands/npm-help.md b/docs/content/commands/npm-help.md deleted file mode 100644 index 83c595db696b9..0000000000000 --- a/docs/content/commands/npm-help.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: npm-help -section: 1 -description: Get help on npm ---- - -### Synopsis - - - - - -```bash -npm help [] - -alias: hlep -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -If supplied a topic, then show the appropriate documentation page. - -If the topic does not exist, or if multiple terms are provided, then npm -will run the `help-search` command to find a match. Note that, if -`help-search` finds a single subject, then it will run `help` on that -topic, so unique matches are equivalent to specifying a topic name. - -### Configuration - - - - -#### `viewer` - -* Default: "man" on Posix, "browser" on Windows -* Type: String - -The program to use to view help content. - -Set to `"browser"` to view html help content in the default web browser. - - - - - - -### See Also - -* [npm](/commands/npm) -* [npm folders](/configuring-npm/folders) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [package.json](/configuring-npm/package-json) -* [npm help-search](/commands/npm-help-search) diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md deleted file mode 100644 index f3124a7768dfc..0000000000000 --- a/docs/content/commands/npm-init.md +++ /dev/null @@ -1,327 +0,0 @@ ---- -title: npm-init -section: 1 -description: Create a package.json file ---- - -### Synopsis - - - - - -```bash -npm init (same as `npx ) -npm init <@scope> (same as `npx <@scope>/create`) - -aliases: create, innit -``` - - - - - - -### Description - -`npm init ` can be used to set up a new or existing npm -package. - -`initializer` in this case is an npm package named `create-`, -which will be installed by [`npm-exec`](/commands/npm-exec), and then have its -main bin executed -- presumably creating or updating `package.json` and -running any other initialization-related operations. - -The init command is transformed to a corresponding `npm exec` operation as -follows: - -* `npm init foo` -> `npm exec create-foo` -* `npm init @usr/foo` -> `npm exec @usr/create-foo` -* `npm init @usr` -> `npm exec @usr/create` -* `npm init @usr@2.0.0` -> `npm exec @usr/create@2.0.0` -* `npm init @usr/foo@2.0.0` -> `npm exec @usr/create-foo@2.0.0` - -If the initializer is omitted (by just calling `npm init`), init will fall -back to legacy init behavior. It will ask you a bunch of questions, and -then write a package.json for you. It will attempt to make reasonable -guesses based on existing fields, dependencies, and options selected. It is -strictly additive, so it will keep any fields and values that were already -set. You can also use `-y`/`--yes` to skip the questionnaire altogether. If -you pass `--scope`, it will create a scoped package. - -*Note:* if a user already has the `create-` package -globally installed, that will be what `npm init` uses. If you want npm -to use the latest version, or another specific version you must specify -it: - -* `npm init foo@latest` # fetches and runs the latest `create-foo` from - the registry -* `npm init foo@1.2.3` # runs `create-foo@1.2.3` specifically - -#### Forwarding additional options - -Any additional options will be passed directly to the command, so `npm init -foo -- --hello` will map to `npm exec -- create-foo --hello`. - -To better illustrate how options are forwarded, here's a more evolved -example showing options passed to both the **npm cli** and a create package, -both following commands are equivalent: - -- `npm init foo -y --registry= -- --hello -a` -- `npm exec -y --registry= -- create-foo --hello -a` - -### Examples - -Create a new React-based project using -[`create-react-app`](https://npm.im/create-react-app): - -```bash -$ npm init react-app ./my-react-app -``` - -Create a new `esm`-compatible package using -[`create-esm`](https://npm.im/create-esm): - -```bash -$ mkdir my-esm-lib && cd my-esm-lib -$ npm init esm --yes -``` - -Generate a plain old package.json using legacy init: - -```bash -$ mkdir my-npm-pkg && cd my-npm-pkg -$ git init -$ npm init -``` - -Generate it without having it ask any questions: - -```bash -$ npm init -y -``` - -### Workspaces support - -It's possible to create a new workspace within your project by using the -`workspace` config option. When using `npm init -w ` the cli will -create the folders and boilerplate expected while also adding a reference -to your project `package.json` `"workspaces": []` property in order to make -sure that new generated **workspace** is properly set up as such. - -Given a project with no workspaces, e.g: - -``` -. -+-- package.json -``` - -You may generate a new workspace using the legacy init: - -```bash -$ npm init -w packages/a -``` - -That will generate a new folder and `package.json` file, while also updating -your top-level `package.json` to add the reference to this new workspace: - -``` -. -+-- package.json -`-- packages - `-- a - `-- package.json -``` - -The workspaces init also supports the `npm init -w ` -syntax, following the same set of rules explained earlier in the initial -**Description** section of this page. Similar to the previous example of -creating a new React-based project using -[`create-react-app`](https://npm.im/create-react-app), the following syntax -will make sure to create the new react app as a nested **workspace** within your -project and configure your `package.json` to recognize it as such: - -```bash -npm init -w packages/my-react-app react-app . -``` - -This will make sure to generate your react app as expected, one important -consideration to have in mind is that `npm exec` is going to be run in the -context of the newly created folder for that workspace, and that's the reason -why in this example the initializer uses the initializer name followed with a -dot to represent the current directory in that context, e.g: `react-app .`: - -``` -. -+-- package.json -`-- packages - +-- a - | `-- package.json - `-- my-react-app - +-- README - +-- package.json - `-- ... -``` - -### Configuration - - - - -#### `yes` - -* Default: null -* Type: null or Boolean - -Automatically answer "yes" to any prompts that npm might print on the -command line. - - - - -#### `force` - -* Default: false -* Type: Boolean - -Removes various protections against unfortunate side effects, common -mistakes, unnecessary performance degradation, and malicious input. - -* Allow clobbering non-npm files in global installs. -* Allow the `npm version` command to work on an unclean git repository. -* Allow deleting the cache folder with `npm cache clean`. -* Allow installing packages that have an `engines` declaration requiring a - different version of npm. -* Allow installing packages that have an `engines` declaration requiring a - different version of `node`, even if `--engine-strict` is enabled. -* Allow `npm audit fix` to install modules outside your stated dependency - range (including SemVer-major changes). -* Allow unpublishing all versions of a published package. -* Allow conflicting peerDependencies to be installed in the root project. -* Implicitly set `--yes` during `npm init`. -* Allow clobbering existing values in `npm pkg` -* Allow unpublishing of entire packages (not just a single version). - -If you don't have a clear idea of what you want to do, it is strongly -recommended that you do not use this option! - - - - -#### `scope` - -* Default: the scope of the current project, if any, or "" -* Type: String - -Associate an operation with a scope for a scoped registry. - -Useful when logging in to or out of a private registry: - -``` -# log in, linking the scope to the custom registry -npm login --scope=@mycorp --registry=https://registry.mycorp.com - -# log out, removing the link and the auth token -npm logout --scope=@mycorp -``` - -This will cause `@mycorp` to be mapped to the registry for future -installation of packages specified according to the pattern -`@mycorp/package`. - -This will also cause `npm init` to create a scoped package. - -``` -# accept all defaults, and create a package named "@foo/whatever", -# instead of just named "whatever" -npm init --scope=@foo --yes -``` - - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces-update` - -* Default: true -* Type: Boolean - -If set to true, the npm cli will run an update after operations that may -possibly change the workspaces installed to the `node_modules` folder. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - - -### See Also - -* [package spec](/using-npm/package-spec) -* [init-package-json module](http://npm.im/init-package-json) -* [package.json](/configuring-npm/package-json) -* [npm version](/commands/npm-version) -* [npm scope](/using-npm/scope) -* [npm exec](/commands/npm-exec) -* [npm workspaces](/using-npm/workspaces) diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md deleted file mode 100644 index 4de56d372fefe..0000000000000 --- a/docs/content/commands/npm-install-ci-test.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -title: npm-install-ci-test -section: 1 -description: Install a project with a clean slate and run tests ---- - -### Synopsis - - - - - -```bash -npm install-ci-test - -alias: cit -``` - - - - - - -### Description - -This command runs `npm ci` followed immediately by `npm test`. - -### Configuration - - - - -#### `save` - -* Default: `true` unless when using `npm update` where it defaults to `false` -* Type: Boolean - -Save installed packages to a `package.json` file as dependencies. - -When used with the `npm rm` command, removes the dependency from -`package.json`. - -Will also prevent writing to `package-lock.json` if set to `false`. - - - - -#### `save-exact` - -* Default: false -* Type: Boolean - -Dependencies saved to package.json will be configured with an exact version -rather than using npm's default semver range operator. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `global-style` - -* Default: false -* Type: Boolean - -Causes npm to install the package into your local `node_modules` folder with -the same layout it uses with the global `node_modules` folder. Only your -direct dependencies will show in `node_modules` and everything they depend -on will be flattened in their `node_modules` folders. This obviously will -eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` -will be preferred. - - - - -#### `legacy-bundling` - -* Default: false -* Type: Boolean - -Causes npm to install the package such that versions of npm prior to 1.4, -such as the one included with node 0.8, can install the package. This -eliminates all automatic deduping. If used with `global-style` this option -will be preferred. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `strict-peer-deps` - -* Default: false -* Type: Boolean - -If set to `true`, and `--legacy-peer-deps` is not set, then _any_ -conflicting `peerDependencies` will be treated as an install failure, even -if npm could reasonably guess the appropriate resolution based on non-peer -dependency relationships. - -By default, conflicting `peerDependencies` deep in the dependency graph will -be resolved using the nearest non-peer dependency specification, even if -doing so will result in some packages receiving a peer dependency outside -the range set in their package's `peerDependencies` object. - -When such and override is performed, a warning is printed, explaining the -conflict and the packages involved. If `--strict-peer-deps` is set, then -this warning is treated as a failure. - - - - -#### `package-lock` - -* Default: true -* Type: Boolean - -If set to false, then ignore `package-lock.json` files when installing. This -will also prevent _writing_ `package-lock.json` if `save` is true. - -This configuration does not affect `npm ci`. - - - - -#### `foreground-scripts` - -* Default: false -* Type: Boolean - -Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) -scripts for installed packages in the foreground process, sharing standard -input, output, and error with the main npm process. - -Note that this will generally make installs run slower, and be much noisier, -but can be useful for debugging. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `audit` - -* Default: true -* Type: Boolean - -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `fund` - -* Default: true -* Type: Boolean - -When "true" displays the message at the end of each `npm install` -acknowledging the number of dependencies looking for funding. See [`npm -fund`](/commands/npm-fund) for details. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [npm install-test](/commands/npm-install-test) -* [npm ci](/commands/npm-ci) -* [npm test](/commands/npm-test) diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md deleted file mode 100644 index 4dad775e927c9..0000000000000 --- a/docs/content/commands/npm-install-test.md +++ /dev/null @@ -1,327 +0,0 @@ ---- -title: npm-install-test -section: 1 -description: Install package(s) and run tests ---- - -### Synopsis - - - - - -```bash -npm install-test [ ...] - -alias: it -``` - - - - - - -### Description - -This command runs an `npm install` followed immediately by an `npm test`. It -takes exactly the same arguments as `npm install`. - -### Configuration - - - - -#### `save` - -* Default: `true` unless when using `npm update` where it defaults to `false` -* Type: Boolean - -Save installed packages to a `package.json` file as dependencies. - -When used with the `npm rm` command, removes the dependency from -`package.json`. - -Will also prevent writing to `package-lock.json` if set to `false`. - - - - -#### `save-exact` - -* Default: false -* Type: Boolean - -Dependencies saved to package.json will be configured with an exact version -rather than using npm's default semver range operator. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `global-style` - -* Default: false -* Type: Boolean - -Causes npm to install the package into your local `node_modules` folder with -the same layout it uses with the global `node_modules` folder. Only your -direct dependencies will show in `node_modules` and everything they depend -on will be flattened in their `node_modules` folders. This obviously will -eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` -will be preferred. - - - - -#### `legacy-bundling` - -* Default: false -* Type: Boolean - -Causes npm to install the package such that versions of npm prior to 1.4, -such as the one included with node 0.8, can install the package. This -eliminates all automatic deduping. If used with `global-style` this option -will be preferred. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `strict-peer-deps` - -* Default: false -* Type: Boolean - -If set to `true`, and `--legacy-peer-deps` is not set, then _any_ -conflicting `peerDependencies` will be treated as an install failure, even -if npm could reasonably guess the appropriate resolution based on non-peer -dependency relationships. - -By default, conflicting `peerDependencies` deep in the dependency graph will -be resolved using the nearest non-peer dependency specification, even if -doing so will result in some packages receiving a peer dependency outside -the range set in their package's `peerDependencies` object. - -When such and override is performed, a warning is printed, explaining the -conflict and the packages involved. If `--strict-peer-deps` is set, then -this warning is treated as a failure. - - - - -#### `package-lock` - -* Default: true -* Type: Boolean - -If set to false, then ignore `package-lock.json` files when installing. This -will also prevent _writing_ `package-lock.json` if `save` is true. - -This configuration does not affect `npm ci`. - - - - -#### `foreground-scripts` - -* Default: false -* Type: Boolean - -Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) -scripts for installed packages in the foreground process, sharing standard -input, output, and error with the main npm process. - -Note that this will generally make installs run slower, and be much noisier, -but can be useful for debugging. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `audit` - -* Default: true -* Type: Boolean - -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `fund` - -* Default: true -* Type: Boolean - -When "true" displays the message at the end of each `npm install` -acknowledging the number of dependencies looking for funding. See [`npm -fund`](/commands/npm-fund) for details. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [npm install](/commands/npm-install) -* [npm install-ci-test](/commands/npm-install-ci-test) -* [npm test](/commands/npm-test) diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md deleted file mode 100644 index 81a31acfa0272..0000000000000 --- a/docs/content/commands/npm-link.md +++ /dev/null @@ -1,407 +0,0 @@ ---- -title: npm-link -section: 1 -description: Symlink a package folder ---- - -### Synopsis - - - - - -```bash -npm link [] - -alias: ln -``` - - - - - - -### Description - -This is handy for installing your own stuff, so that you can work on it and -test iteratively without having to continually rebuild. - -Package linking is a two-step process. - -First, `npm link` in a package folder with no arguments will create a -symlink in the global folder `{prefix}/lib/node_modules/` that -links to the package where the `npm link` command was executed. It will -also link any bins in the package to `{prefix}/bin/{name}`. Note that -`npm link` uses the global prefix (see `npm prefix -g` for its value). - -Next, in some other location, `npm link package-name` will create a -symbolic link from globally-installed `package-name` to `node_modules/` of -the current folder. - -Note that `package-name` is taken from `package.json`, _not_ from the -directory name. - -The package name can be optionally prefixed with a scope. See -[`scope`](/using-npm/scope). The scope must be preceded by an @-symbol and -followed by a slash. - -When creating tarballs for `npm publish`, the linked packages are -"snapshotted" to their current state by resolving the symbolic links, if -they are included in `bundleDependencies`. - -For example: - -```bash -cd ~/projects/node-redis # go into the package directory -npm link # creates global link -cd ~/projects/node-bloggy # go into some other package directory. -npm link redis # link-install the package -``` - -Now, any changes to `~/projects/node-redis` will be reflected in -`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link -should be to the package name, not the directory name for that package. - -You may also shortcut the two steps in one. For example, to do the -above use-case in a shorter way: - -```bash -cd ~/projects/node-bloggy # go into the dir of your main project -npm link ../node-redis # link the dir of your dependency -``` - -The second line is the equivalent of doing: - -```bash -(cd ../node-redis; npm link) -npm link redis -``` - -That is, it first creates a global link, and then links the global -installation target into your project's `node_modules` folder. - -Note that in this case, you are referring to the directory name, -`node-redis`, rather than the package name `redis`. - -If your linked package is scoped (see [`scope`](/using-npm/scope)) your -link command must include that scope, e.g. - -```bash -npm link @myorg/privatepackage -``` - -### Caveat - -Note that package dependencies linked in this way are _not_ saved to -`package.json` by default, on the assumption that the intention is to have -a link stand in for a regular non-link dependency. Otherwise, for example, -if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace -the `^3.0.1` dependency with `file:../path/to/node-redis`, which you -probably don't want! Additionally, other users or developers on your -project would run into issues if they do not have their folders set up -exactly the same as yours. - -If you are adding a _new_ dependency as a link, you should add it to the -relevant metadata by running `npm install --package-lock-only`. - -If you _want_ to save the `file:` reference in your `package.json` and -`package-lock.json` files, you can use `npm link --save` to do so. - -### Workspace Usage - -`npm link --workspace ` will link the relevant package as a -dependency of the specified workspace(s). Note that It may actually be -linked into the parent project's `node_modules` folder, if there are no -conflicting dependencies. - -`npm link --workspace ` will create a global link to the specified -workspace(s). - -### Configuration - - - - -#### `save` - -* Default: `true` unless when using `npm update` where it defaults to `false` -* Type: Boolean - -Save installed packages to a `package.json` file as dependencies. - -When used with the `npm rm` command, removes the dependency from -`package.json`. - -Will also prevent writing to `package-lock.json` if set to `false`. - - - - -#### `save-exact` - -* Default: false -* Type: Boolean - -Dependencies saved to package.json will be configured with an exact version -rather than using npm's default semver range operator. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `global-style` - -* Default: false -* Type: Boolean - -Causes npm to install the package into your local `node_modules` folder with -the same layout it uses with the global `node_modules` folder. Only your -direct dependencies will show in `node_modules` and everything they depend -on will be flattened in their `node_modules` folders. This obviously will -eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` -will be preferred. - - - - -#### `legacy-bundling` - -* Default: false -* Type: Boolean - -Causes npm to install the package such that versions of npm prior to 1.4, -such as the one included with node 0.8, can install the package. This -eliminates all automatic deduping. If used with `global-style` this option -will be preferred. - - - - -#### `strict-peer-deps` - -* Default: false -* Type: Boolean - -If set to `true`, and `--legacy-peer-deps` is not set, then _any_ -conflicting `peerDependencies` will be treated as an install failure, even -if npm could reasonably guess the appropriate resolution based on non-peer -dependency relationships. - -By default, conflicting `peerDependencies` deep in the dependency graph will -be resolved using the nearest non-peer dependency specification, even if -doing so will result in some packages receiving a peer dependency outside -the range set in their package's `peerDependencies` object. - -When such and override is performed, a warning is printed, explaining the -conflict and the packages involved. If `--strict-peer-deps` is set, then -this warning is treated as a failure. - - - - -#### `package-lock` - -* Default: true -* Type: Boolean - -If set to false, then ignore `package-lock.json` files when installing. This -will also prevent _writing_ `package-lock.json` if `save` is true. - -This configuration does not affect `npm ci`. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `audit` - -* Default: true -* Type: Boolean - -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `fund` - -* Default: true -* Type: Boolean - -When "true" displays the message at the end of each `npm install` -acknowledging the number of dependencies looking for funding. See [`npm -fund`](/commands/npm-fund) for details. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [package spec](/using-npm/package-spec) -* [npm developers](/using-npm/developers) -* [package.json](/configuring-npm/package-json) -* [npm install](/commands/npm-install) -* [npm folders](/configuring-npm/folders) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-login.md b/docs/content/commands/npm-login.md deleted file mode 100644 index a3772dc882a9d..0000000000000 --- a/docs/content/commands/npm-login.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: npm-login -section: 1 -description: Login to a registry user account ---- - -### Synopsis - - - - - -```bash -npm login -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Verify a user in the specified registry, and save the credentials to the -`.npmrc` file. If no registry is specified, the default registry will be -used (see [`config`](/using-npm/config)). - -When using `legacy` for your `auth-type`, the username and password, are -read in from prompts. - -To reset your password, go to - -To change your email address, go to - -You may use this command multiple times with the same user account to -authorize on a new machine. When authenticating on a new machine, -the username, password and email address must all match with -your existing record. - -### Configuration - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `scope` - -* Default: the scope of the current project, if any, or "" -* Type: String - -Associate an operation with a scope for a scoped registry. - -Useful when logging in to or out of a private registry: - -``` -# log in, linking the scope to the custom registry -npm login --scope=@mycorp --registry=https://registry.mycorp.com - -# log out, removing the link and the auth token -npm logout --scope=@mycorp -``` - -This will cause `@mycorp` to be mapped to the registry for future -installation of packages specified according to the pattern -`@mycorp/package`. - -This will also cause `npm init` to create a scoped package. - -``` -# accept all defaults, and create a package named "@foo/whatever", -# instead of just named "whatever" -npm init --scope=@foo --yes -``` - - - - - -#### `auth-type` - -* Default: "web" -* Type: "legacy" or "web" - -What authentication strategy to use with `login`. - - - - - - -### See Also - -* [npm registry](/using-npm/registry) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [npm owner](/commands/npm-owner) -* [npm whoami](/commands/npm-whoami) -* [npm token](/commands/npm-token) -* [npm profile](/commands/npm-profile) diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md deleted file mode 100644 index f0dd5cb856eae..0000000000000 --- a/docs/content/commands/npm-logout.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: npm-logout -section: 1 -description: Log out of the registry ---- - -### Synopsis - - - - - -```bash -npm logout -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -When logged into a registry that supports token-based authentication, tell -the server to end this token's session. This will invalidate the token -everywhere you're using it, not just for the current environment. - -When logged into a legacy registry that uses username and password -authentication, this will clear the credentials in your user configuration. -In this case, it will _only_ affect the current environment. - -If `--scope` is provided, this will find the credentials for the registry -connected to that scope, if set. - -### Configuration - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `scope` - -* Default: the scope of the current project, if any, or "" -* Type: String - -Associate an operation with a scope for a scoped registry. - -Useful when logging in to or out of a private registry: - -``` -# log in, linking the scope to the custom registry -npm login --scope=@mycorp --registry=https://registry.mycorp.com - -# log out, removing the link and the auth token -npm logout --scope=@mycorp -``` - -This will cause `@mycorp` to be mapped to the registry for future -installation of packages specified according to the pattern -`@mycorp/package`. - -This will also cause `npm init` to create a scoped package. - -``` -# accept all defaults, and create a package named "@foo/whatever", -# instead of just named "whatever" -npm init --scope=@foo --yes -``` - - - - - - - -### See Also - -* [npm adduser](/commands/npm-adduser) -* [npm registry](/using-npm/registry) -* [npm config](/commands/npm-config) -* [npm whoami](/commands/npm-whoami) diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md deleted file mode 100644 index 0e01dc3409011..0000000000000 --- a/docs/content/commands/npm-ls.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: npm-ls -section: 1 -description: List installed packages ---- - -### Synopsis - - - - - -```bash -npm ls - -alias: list -``` - - - - - - -### Description - -This command will print to stdout all the versions of packages that are -installed, as well as their dependencies when `--all` is specified, in a -tree structure. - -Note: to get a "bottoms up" view of why a given package is included in the -tree at all, use [`npm explain`](/commands/npm-explain). - -Positional arguments are `name@version-range` identifiers, which will limit -the results to only the paths to the packages named. Note that nested -packages will *also* show the paths to the specified packages. For -example, running `npm ls promzard` in npm's source tree will show: - -```bash -npm@@VERSION@ /path/to/npm -└─┬ init-package-json@0.0.4 - └── promzard@0.1.5 -``` - -It will print out extraneous, missing, and invalid packages. - -If a project specifies git urls for dependencies these are shown -in parentheses after the `name@version` to make it easier for users to -recognize potential forks of a project. - -The tree shown is the logical dependency tree, based on package -dependencies, not the physical layout of your `node_modules` folder. - -When run as `ll` or `la`, it shows extended information by default. - -### Note: Design Changes Pending - -The `npm ls` command's output and behavior made a _ton_ of sense when npm -created a `node_modules` folder that naively nested every dependency. In -such a case, the logical dependency graph and physical tree of packages on -disk would be roughly identical. - -With the advent of automatic install-time deduplication of dependencies in -npm v3, the `ls` output was modified to display the logical dependency -graph as a tree structure, since this was more useful to most users. -However, without using `npm ls -l`, it became impossible to show _where_ a -package was actually installed much of the time! - -With the advent of automatic installation of `peerDependencies` in npm v7, -this gets even more curious, as `peerDependencies` are logically -"underneath" their dependents in the dependency graph, but are always -physically at or above their location on disk. - -Also, in the years since npm got an `ls` command (in version 0.0.2!), -dependency graphs have gotten much larger as a general rule. Therefore, in -order to avoid dumping an excessive amount of content to the terminal, `npm -ls` now only shows the _top_ level dependencies, unless `--all` is -provided. - -A thorough re-examination of the use cases, intention, behavior, and output -of this command, is currently underway. Expect significant changes to at -least the default human-readable `npm ls` output in npm v8. - -### Configuration - - - - -#### `all` - -* Default: false -* Type: Boolean - -When running `npm outdated` and `npm ls`, setting `--all` will show all -outdated or installed packages, rather than only those directly depended -upon by the current project. - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `long` - -* Default: false -* Type: Boolean - -Show extended information in `ls`, `search`, and `help-search`. - - - - -#### `parseable` - -* Default: false -* Type: Boolean - -Output parseable results from commands that write to standard output. For -`npm search`, this will be tab-separated table format. - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `depth` - -* Default: `Infinity` if `--all` is set, otherwise `1` -* Type: null or Number - -The depth to go when recursing packages for `npm ls`. - -If not set, `npm ls` will show only the immediate dependencies of the root -project. If `--all` is set, then npm will show all dependencies by default. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `link` - -* Default: false -* Type: Boolean - -Used with `npm ls`, limiting output to only those packages that are linked. - - - - -#### `package-lock-only` - -* Default: false -* Type: Boolean - -If set to true, the current operation will only use the `package-lock.json`, -ignoring `node_modules`. - -For `update` this means only the `package-lock.json` will be updated, -instead of checking `node_modules` and downloading dependencies. - -For `list` this means the output will be based on the tree described by the -`package-lock.json`, rather than the contents of `node_modules`. - - - - -#### `unicode` - -* Default: false on windows, true on mac/unix systems with a unicode locale, - as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables. -* Type: Boolean - -When set to true, npm uses unicode characters in the tree output. When -false, it uses ascii characters instead of unicode glyphs. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [package spec](/using-npm/package-spec) -* [npm explain](/commands/npm-explain) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [npm folders](/configuring-npm/folders) -* [npm explain](/commands/npm-explain) -* [npm install](/commands/npm-install) -* [npm link](/commands/npm-link) -* [npm prune](/commands/npm-prune) -* [npm outdated](/commands/npm-outdated) -* [npm update](/commands/npm-update) diff --git a/docs/content/commands/npm-org.md b/docs/content/commands/npm-org.md deleted file mode 100644 index 975581c860df6..0000000000000 --- a/docs/content/commands/npm-org.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: npm-org -section: 1 -description: Manage orgs ---- - -### Synopsis - - - - - -```bash -npm org set orgname username [developer | admin | owner] -npm org rm orgname username -npm org ls orgname [] - -alias: ogr -``` - - - - - - -Note: This command is unaware of workspaces. - -### Example - -Add a new developer to an org: - -```bash -$ npm org set my-org @mx-smith -``` - -Add a new admin to an org (or change a developer to an admin): - -```bash -$ npm org set my-org @mx-santos admin -``` - -Remove a user from an org: - -```bash -$ npm org rm my-org mx-santos -``` - -List all users in an org: - -```bash -$ npm org ls my-org -``` - -List all users in JSON format: - -```bash -$ npm org ls my-org --json -``` - -See what role a user has in an org: - -```bash -$ npm org ls my-org @mx-santos -``` - -### Description - -You can use the `npm org` commands to manage and view users of an -organization. It supports adding and removing users, changing their roles, -listing them, and finding specific ones and their roles. - -### Configuration - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `otp` - -* Default: null -* Type: null or String - -This is a one-time password from a two-factor authenticator. It's needed -when publishing or changing package permissions with `npm access`. - -If not set, and a registry response fails with a challenge for a one-time -password, npm will prompt on the command line for one. - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `parseable` - -* Default: false -* Type: Boolean - -Output parseable results from commands that write to standard output. For -`npm search`, this will be tab-separated table format. - - - - - - -### See Also - -* [using orgs](/using-npm/orgs) -* [Documentation on npm Orgs](https://docs.npmjs.com/orgs/) diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md deleted file mode 100644 index ebc29ef693939..0000000000000 --- a/docs/content/commands/npm-owner.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: npm-owner -section: 1 -description: Manage package owners ---- - -### Synopsis - - - - - -```bash -npm owner add -npm owner rm -npm owner ls - -alias: author -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Manage ownership of published packages. - -* ls: List all the users who have access to modify a package and push new - versions. Handy when you need to know who to bug for help. -* add: Add a new user as a maintainer of a package. This user is enabled - to modify metadata, publish new versions, and add other owners. -* rm: Remove a user from the package owner list. This immediately revokes - their privileges. - -Note that there is only one level of access. Either you can modify a package, -or you can't. Future versions may contain more fine-grained access levels, but -that is not implemented at this time. - -If you have two-factor authentication enabled with `auth-and-writes` (see -[`npm-profile`](/commands/npm-profile)) then you'll need to include an otp -on the command line when changing ownership with `--otp`. - -### Configuration - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `otp` - -* Default: null -* Type: null or String - -This is a one-time password from a two-factor authenticator. It's needed -when publishing or changing package permissions with `npm access`. - -If not set, and a registry response fails with a challenge for a one-time -password, npm will prompt on the command line for one. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - - - -### See Also - -* [package spec](/using-npm/package-spec) -* [npm profile](/commands/npm-profile) -* [npm publish](/commands/npm-publish) -* [npm registry](/using-npm/registry) -* [npm adduser](/commands/npm-adduser) diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md deleted file mode 100644 index 7921042eae8fe..0000000000000 --- a/docs/content/commands/npm-pack.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: npm-pack -section: 1 -description: Create a tarball from a package ---- - -### Synopsis - - - - - -```bash -npm pack -``` - - - - - - -### Configuration - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `pack-destination` - -* Default: "." -* Type: String - -Directory in which `npm pack` will save tarballs. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - - -### Description - -For anything that's installable (that is, a package folder, tarball, -tarball url, git url, name@tag, name@version, name, or scoped name), this -command will fetch it to the cache, copy the tarball to the current working -directory as `-.tgz`, and then write the filenames out to -stdout. - -If the same package is specified multiple times, then the file will be -overwritten the second time. - -If no arguments are supplied, then npm packs the current package folder. - -### See Also - -* [package spec](/using-npm/package-spec) -* [npm-packlist package](http://npm.im/npm-packlist) -* [npm cache](/commands/npm-cache) -* [npm publish](/commands/npm-publish) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md deleted file mode 100644 index 161d7292f8c97..0000000000000 --- a/docs/content/commands/npm-ping.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: npm-ping -section: 1 -description: Ping npm registry ---- - -### Synopsis - - - - - -```bash -npm ping -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Ping the configured or given npm registry and verify authentication. -If it works it will output something like: - -```bash -npm notice PING https://registry.npmjs.org/ -npm notice PONG 255ms -``` -otherwise you will get an error: -```bash -npm notice PING http://foo.com/ -npm ERR! code E404 -npm ERR! 404 Not Found - GET http://www.foo.com/-/ping?write=true -``` - -### Configuration - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - - - -### See Also - -* [npm doctor](/commands/npm-doctor) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-prefix.md b/docs/content/commands/npm-prefix.md deleted file mode 100644 index 39328bcc88a14..0000000000000 --- a/docs/content/commands/npm-prefix.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: npm-prefix -section: 1 -description: Display prefix ---- - -### Synopsis - - - - - -```bash -npm prefix [-g] -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Print the local prefix to standard output. This is the closest parent directory -to contain a `package.json` file or `node_modules` directory, unless `-g` is -also specified. - -If `-g` is specified, this will be the value of the global prefix. See -[`npm config`](/commands/npm-config) for more detail. - -### Example - -```bash -npm prefix -/usr/local/projects/foo -``` - -```bash -npm prefix -g -/usr/local -``` - -### Configuration - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - - - -### See Also - -* [npm root](/commands/npm-root) -* [npm bin](/commands/npm-bin) -* [npm folders](/configuring-npm/folders) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md deleted file mode 100644 index 6cbfc2ad438cd..0000000000000 --- a/docs/content/commands/npm-prune.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: npm-prune -section: 1 -description: Remove extraneous packages ---- - -### Synopsis - - - - - -```bash -npm prune [[<@scope>/]...] -``` - - - - - - -### Description - -This command removes "extraneous" packages. If a package name is provided, -then only packages matching one of the supplied names are removed. - -Extraneous packages are those present in the `node_modules` folder that are -not listed as any package's dependency list. - -If the `--production` flag is specified or the `NODE_ENV` environment -variable is set to `production`, this command will remove the packages -specified in your `devDependencies`. Setting `--no-production` will negate -`NODE_ENV` being set to `production`. - -If the `--dry-run` flag is used then no changes will actually be made. - -If the `--json` flag is used, then the changes `npm prune` made (or would -have made with `--dry-run`) are printed as a JSON object. - -In normal operation, extraneous modules are pruned automatically, so you'll -only need this command with the `--production` flag. However, in the real -world, operation is not always "normal". When crashes or mistakes happen, -this command can help clean up any resulting garbage. - -### Configuration - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `foreground-scripts` - -* Default: false -* Type: Boolean - -Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) -scripts for installed packages in the foreground process, sharing standard -input, output, and error with the main npm process. - -Note that this will generally make installs run slower, and be much noisier, -but can be useful for debugging. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [npm uninstall](/commands/npm-uninstall) -* [npm folders](/configuring-npm/folders) -* [npm ls](/commands/npm-ls) diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md deleted file mode 100644 index 0c1b777c881bb..0000000000000 --- a/docs/content/commands/npm-publish.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: npm-publish -section: 1 -description: Publish a package ---- - -### Synopsis - - - - - -```bash -npm publish -``` - - - - - - -### Description - -Publishes a package to the registry so that it can be installed by name. - -By default npm will publish to the public registry. This can be -overridden by specifying a different default registry or using a -[`scope`](/using-npm/scope) in the name, combined with a -scope-configured registry (see -[`package.json`](/configuring-npm/package-json)). - - -A `package` is interpreted the same way as other commands (like -`npm install` and can be: - -* a) a folder containing a program described by a - [`package.json`](/configuring-npm/package-json) file -* b) a gzipped tarball containing (a) -* c) a url that resolves to (b) -* d) a `@` that is published on the registry (see - [`registry`](/using-npm/registry)) with (c) -* e) a `@` (see [`npm dist-tag`](/commands/npm-dist-tag)) that - points to (d) -* f) a `` that has a "latest" tag satisfying (e) -* g) a `` that resolves to (a) - -The publish will fail if the package name and version combination already -exists in the specified registry. - -Once a package is published with a given name and version, that specific -name and version combination can never be used again, even if it is removed -with [`npm unpublish`](/commands/npm-unpublish). - -As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the -tarball will be submitted to the registry during publication. Subsequent -installs will use the strongest supported algorithm to verify downloads. - -Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures -out the files to be included and packs them into a tarball to be uploaded -to the registry. - -### Files included in package - -To see what will be included in your package, run `npx npm-packlist`. All -files are included by default, with the following exceptions: - -- Certain files that are relevant to package installation and distribution - are always included. For example, `package.json`, `README.md`, - `LICENSE`, and so on. - -- If there is a "files" list in - [`package.json`](/configuring-npm/package-json), then only the files - specified will be included. (If directories are specified, then they - will be walked recursively and their contents included, subject to the - same ignore rules.) - -- If there is a `.gitignore` or `.npmignore` file, then ignored files in - that and all child directories will be excluded from the package. If - _both_ files exist, then the `.gitignore` is ignored, and only the - `.npmignore` is used. - - `.npmignore` files follow the [same pattern - rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) - as `.gitignore` files - -- If the file matches certain patterns, then it will _never_ be included, - unless explicitly added to the `"files"` list in `package.json`, or - un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file. - -- Symbolic links are never included in npm packages. - - -See [`developers`](/using-npm/developers) for full details on what's -included in the published package, as well as details on how the package is -built. - -### Configuration - - - - -#### `tag` - -* Default: "latest" -* Type: String - -If you ask npm to install a package and don't tell it a specific version, -then it will install the specified tag. - -Also the tag that is added to the package@version specified by the `npm tag` -command, if no explicit tag is given. - -When used by the `npm diff` command, this is the tag used to fetch the -tarball that will be compared with the local files by default. - - - - -#### `access` - -* Default: 'public' for new packages, existing packages it will not change the - current level -* Type: null, "restricted", or "public" - -If do not want your scoped package to be publicly viewable (and installable) -set `--access=restricted`. - -Unscoped packages can not be set to `restricted`. - -Note: This defaults to not changing the current access level for existing -packages. Specifying a value of `restricted` or `public` during publish will -change the access for an existing package the same way that `npm access set -status` would. - - - - -#### `dry-run` - -* Default: false -* Type: Boolean - -Indicates that you don't want npm to make any changes and that it should -only report what it would have done. This can be passed into any of the -commands that modify your local installation, eg, `install`, `update`, -`dedupe`, `uninstall`, as well as `pack` and `publish`. - -Note: This is NOT honored by other network related commands, eg `dist-tags`, -`owner`, etc. - - - - -#### `otp` - -* Default: null -* Type: null or String - -This is a one-time password from a two-factor authenticator. It's needed -when publishing or changing package permissions with `npm access`. - -If not set, and a registry response fails with a challenge for a one-time -password, npm will prompt on the command line for one. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - - -### See Also - -* [package spec](/using-npm/package-spec) -* [npm-packlist package](http://npm.im/npm-packlist) -* [npm registry](/using-npm/registry) -* [npm scope](/using-npm/scope) -* [npm adduser](/commands/npm-adduser) -* [npm owner](/commands/npm-owner) -* [npm deprecate](/commands/npm-deprecate) -* [npm dist-tag](/commands/npm-dist-tag) -* [npm pack](/commands/npm-pack) -* [npm profile](/commands/npm-profile) diff --git a/docs/content/commands/npm-query.md b/docs/content/commands/npm-query.md deleted file mode 100644 index c6303c2eb963d..0000000000000 --- a/docs/content/commands/npm-query.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: npm-query -section: 1 -description: Dependency selector query ---- - -### Synopsis - - - - - -```bash -npm query -``` - - - - - - -### Description - -The `npm query` command allows for usage of css selectors in order to retrieve -an array of dependency objects. - -### Piping npm query to other commands - -```bash -# find all dependencies with postinstall scripts & uninstall them -npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {} - -# find all git dependencies & explain who requires them -npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {} -``` - -### Extended Use Cases & Queries - -```stylus -// all deps -* - -// all direct deps -:root > * - -// direct production deps -:root > .prod - -// direct development deps -:root > .dev - -// any peer dep of a direct deps -:root > * > .peer - -// any workspace dep -.workspace - -// all workspaces that depend on another workspace -.workspace > .workspace - -// all workspaces that have peer deps -.workspace:has(.peer) - -// any dep named "lodash" -// equivalent to [name="lodash"] -#lodash - -// any deps named "lodash" & within semver range ^"1.2.3" -#lodash@^1.2.3 -// equivalent to... -[name="lodash"]:semver(^1.2.3) - -// get the hoisted node for a given semver range -#lodash@^1.2.3:not(:deduped) - -// querying deps with a specific version -#lodash@2.1.5 -// equivalent to... -[name="lodash"][version="2.1.5"] - -// has any deps -:has(*) - -// deps with no other deps (ie. "leaf" nodes) -:empty - -// manually querying git dependencies -[repository^=github:], -[repository^=git:], -[repository^=https://github.com], -[repository^=http://github.com], -[repository^=https://github.com], -[repository^=+git:...] - -// querying for all git dependencies -:type(git) - -// get production dependencies that aren't also dev deps -.prod:not(.dev) - -// get dependencies with specific licenses -[license=MIT], [license=ISC] - -// find all packages that have @ruyadorno as a contributor -:attr(contributors, [email=ruyadorno@github.com]) -``` - -### Example Response Output - -- an array of dependency objects is returned which can contain multiple copies of the same package which may or may not have been linked or deduped - -```json -[ - { - "name": "", - "version": "", - "description": "", - "homepage": "", - "bugs": {}, - "author": {}, - "license": {}, - "funding": {}, - "files": [], - "main": "", - "browser": "", - "bin": {}, - "man": [], - "directories": {}, - "repository": {}, - "scripts": {}, - "config": {}, - "dependencies": {}, - "devDependencies": {}, - "optionalDependencies": {}, - "bundledDependencies": {}, - "peerDependencies": {}, - "peerDependenciesMeta": {}, - "engines": {}, - "os": [], - "cpu": [], - "workspaces": {}, - "keywords": [], - ... - }, - ... -``` - -### Configuration - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - -## See Also - -* [dependency selectors](/using-npm/dependency-selectors) - diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md deleted file mode 100644 index 6851b4ddff087..0000000000000 --- a/docs/content/commands/npm-rebuild.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: npm-rebuild -section: 1 -description: Rebuild a package ---- - -### Synopsis - - - - - -```bash -npm rebuild [] ...] - -alias: rb -``` - - - - - - -### Description - -This command runs the `npm build` command on the matched folders. This is -useful when you install a new version of node, and must recompile all your -C++ addons with the new binary. It is also useful when installing with -`--ignore-scripts` and `--no-bin-links`, to explicitly choose which -packages to build and/or link bins. - -If one or more package specs are provided, then only packages with a -name and version matching one of the specifiers will be rebuilt. - -### Configuration - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - -#### `bin-links` - -* Default: true -* Type: Boolean - -Tells npm to create symlinks (or `.cmd` shims on Windows) for package -executables. - -Set to false to have it not do this. This can be used to work around the -fact that some file systems don't support symlinks, even on ostensibly Unix -systems. - - - - -#### `foreground-scripts` - -* Default: false -* Type: Boolean - -Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) -scripts for installed packages in the foreground process, sharing standard -input, output, and error with the main npm process. - -Note that this will generally make installs run slower, and be much noisier, -but can be useful for debugging. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `install-links` - -* Default: true -* Type: Boolean - -When set file: protocol dependencies will be packed and installed as regular -dependencies instead of creating a symlink. This option has no effect on -workspaces. - - - - - - -### See Also - -* [package spec](/using-npm/package-spec) -* [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-repo.md b/docs/content/commands/npm-repo.md deleted file mode 100644 index 4d69a922c63a9..0000000000000 --- a/docs/content/commands/npm-repo.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: npm-repo -section: 1 -description: Open package repository page in the browser ---- - -### Synopsis - - - - - -```bash -npm repo [ [ ...]] -``` - - - - - - -### Description - -This command tries to guess at the likely location of a package's -repository URL, and then tries to open it using the -[`--browser` config](/using-npm/config#browser) param. If no package name is -provided, it will search for a `package.json` in the current folder and use the -`repository` property. - -### Configuration - - - - -#### `browser` - -* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: null, Boolean, or String - -The browser that is called by npm commands to open websites. - -Set to `false` to suppress browser behavior and instead print urls to -terminal. - -Set to `true` to use default system URL opener. - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - - - -### See Also - -* [npm docs](/commands/npm-docs) -* [npm config](/commands/npm-config) diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md deleted file mode 100644 index 048bebb1659bd..0000000000000 --- a/docs/content/commands/npm-restart.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: npm-restart -section: 1 -description: Restart a package ---- - -### Synopsis - - - - - -```bash -npm restart [-- ] -``` - - - - - - -### Description - -This restarts a project. It is equivalent to running `npm run-script -restart`. - -If the current project has a `"restart"` script specified in -`package.json`, then the following scripts will be run: - -1. prerestart -2. restart -3. postrestart - -If it does _not_ have a `"restart"` script specified, but it does have -`stop` and/or `start` scripts, then the following scripts will be run: - -1. prerestart -2. prestop -3. stop -4. poststop -6. prestart -7. start -8. poststart -9. postrestart - -### Configuration - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `script-shell` - -* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows -* Type: null or String - -The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init ` commands. - - - - - - -### See Also - -* [npm run-script](/commands/npm-run-script) -* [npm scripts](/using-npm/scripts) -* [npm test](/commands/npm-test) -* [npm start](/commands/npm-start) -* [npm stop](/commands/npm-stop) -* [npm restart](/commands/npm-restart) diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md deleted file mode 100644 index 40b58e4b33d0b..0000000000000 --- a/docs/content/commands/npm-root.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: npm-root -section: 1 -description: Display npm root ---- - -### Synopsis - - - - - -```bash -npm root -``` - - - - - - -### Description - -Print the effective `node_modules` folder to standard out. - -Useful for using npm in shell scripts that do things with the -`node_modules` folder. For example: - -```bash -#!/bin/bash -global_node_modules="$(npm root --global)" -echo "Global packages installed in: ${global_node_modules}" -``` - -### Configuration - - - - -#### `global` - -* Default: false -* Type: Boolean - -Operates in "global" mode, so that packages are installed into the `prefix` -folder instead of the current working directory. See -[folders](/configuring-npm/folders) for more on the differences in behavior. - -* packages are installed into the `{prefix}/lib/node_modules` folder, instead - of the current working directory. -* bin files are linked to `{prefix}/bin` -* man pages are linked to `{prefix}/share/man` - - - - - - -### See Also - -* [npm prefix](/commands/npm-prefix) -* [npm bin](/commands/npm-bin) -* [npm folders](/configuring-npm/folders) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md deleted file mode 100644 index a68b9b65dcd4f..0000000000000 --- a/docs/content/commands/npm-run-script.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: npm-run-script -section: 1 -description: Run arbitrary package scripts ---- - -### Synopsis - - - - - -```bash -npm run-script [-- ] - -aliases: run, rum, urn -``` - - - - - - -### Description - -This runs an arbitrary command from a package's `"scripts"` object. If no -`"command"` is provided, it will list the available scripts. - -`run[-script]` is used by the test, start, restart, and stop commands, but -can be called directly, as well. When the scripts in the package are -printed out, they're separated into lifecycle (test, start, restart) and -directly-run scripts. - -Any positional arguments are passed to the specified script. Use `--` to -pass `-`-prefixed flags and options which would otherwise be parsed by npm. - -For example: - -```bash -npm run test -- --grep="pattern" -``` - -The arguments will only be passed to the script specified after `npm run` -and not to any `pre` or `post` script. - -The `env` script is a special built-in command that can be used to list -environment variables that will be available to the script at runtime. If an -"env" command is defined in your package, it will take precedence over the -built-in. - -In addition to the shell's pre-existing `PATH`, `npm run` adds -`node_modules/.bin` to the `PATH` provided to scripts. Any binaries -provided by locally-installed dependencies can be used without the -`node_modules/.bin` prefix. For example, if there is a `devDependency` on -`tap` in your package, you should write: - -```bash -"scripts": {"test": "tap test/*.js"} -``` - -instead of - -```bash -"scripts": {"test": "node_modules/.bin/tap test/*.js"} -``` - -The actual shell your script is run within is platform dependent. By default, -on Unix-like systems it is the `/bin/sh` command, on Windows it is -`cmd.exe`. -The actual shell referred to by `/bin/sh` also depends on the system. -You can customize the shell with the -[`script-shell` config](/using-npm/config#script-shell). - -Scripts are run from the root of the package folder, regardless of what the -current working directory is when `npm run` is called. If you want your -script to use different behavior based on what subdirectory you're in, you -can use the `INIT_CWD` environment variable, which holds the full path you -were in when you ran `npm run`. - -`npm run` sets the `NODE` environment variable to the `node` executable -with which `npm` is executed. - -If you try to run a script without having a `node_modules` directory and it -fails, you will be given a warning to run `npm install`, just in case you've -forgotten. - -### Workspaces support - -You may use the [`workspace`](/using-npm/config#workspace) or -[`workspaces`](/using-npm/config#workspaces) configs in order to run an -arbitrary command from a package's `"scripts"` object in the context of the -specified workspaces. If no `"command"` is provided, it will list the available -scripts for each of these configured workspaces. - -Given a project with configured workspaces, e.g: - -``` -. -+-- package.json -`-- packages - +-- a - | `-- package.json - +-- b - | `-- package.json - `-- c - `-- package.json -``` - -Assuming the workspace configuration is properly set up at the root level -`package.json` file. e.g: - -``` -{ - "workspaces": [ "./packages/*" ] -} -``` - -And that each of the configured workspaces has a configured `test` script, -we can run tests in all of them using the -[`workspaces` config](/using-npm/config#workspaces): - -``` -npm test --workspaces -``` - -#### Filtering workspaces - -It's also possible to run a script in a single workspace using the `workspace` -config along with a name or directory path: - -``` -npm test --workspace=a -``` - -The `workspace` config can also be specified multiple times in order to run a -specific script in the context of multiple workspaces. When defining values for -the `workspace` config in the command line, it also possible to use `-w` as a -shorthand, e.g: - -``` -npm test -w a -w b -``` - -This last command will run `test` in both `./packages/a` and `./packages/b` -packages. - -### Configuration - - - - -#### `workspace` - -* Default: -* Type: String (can be set multiple times) - -Enable running a command in the context of the configured workspaces of the -current project while filtering by running only the workspaces defined by -this configuration option. - -Valid values for the `workspace` config are either: - -* Workspace names -* Path to a workspace directory -* Path to a parent workspace directory (will result in selecting all - workspaces within that folder) - -When set for the `npm init` command, this may be set to the folder of a -workspace which does not yet exist, to create the folder and set it up as a -brand new workspace within the project. - -This value is not exported to the environment for child processes. - - - - -#### `workspaces` - -* Default: null -* Type: null or Boolean - -Set to true to run the command in the context of **all** configured -workspaces. - -Explicitly setting this to false will cause commands like `install` to -ignore workspaces altogether. When not set explicitly: - -- Commands that operate on the `node_modules` tree (install, update, etc.) -will link workspaces into the `node_modules` folder. - Commands that do -other things (test, exec, publish, etc.) will operate on the root project, -_unless_ one or more workspaces are specified in the `workspace` config. - -This value is not exported to the environment for child processes. - - - - -#### `include-workspace-root` - -* Default: false -* Type: Boolean - -Include the workspace root when workspaces are enabled for a command. - -When false, specifying individual workspaces via the `workspace` config, or -all workspaces via the `workspaces` flag, will cause npm to operate only on -the specified workspaces, and not on the root project. - -This value is not exported to the environment for child processes. - - - - -#### `if-present` - -* Default: false -* Type: Boolean - -If true, npm will not exit with an error code when `run-script` is invoked -for a script that isn't defined in the `scripts` section of `package.json`. -This option can be used when it's desirable to optionally run a script when -it's present and fail if the script fails. This is useful, for example, when -running scripts that may only apply for some builds in an otherwise generic -CI setup. - -This value is not exported to the environment for child processes. - - - - -#### `ignore-scripts` - -* Default: false -* Type: Boolean - -If true, npm does not run scripts specified in package.json files. - -Note that commands explicitly intended to run a particular script, such as -`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` -will still run their intended script if `ignore-scripts` is set, but they -will *not* run any pre- or post-scripts. - - - - -#### `foreground-scripts` - -* Default: false -* Type: Boolean - -Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) -scripts for installed packages in the foreground process, sharing standard -input, output, and error with the main npm process. - -Note that this will generally make installs run slower, and be much noisier, -but can be useful for debugging. - - - - -#### `script-shell` - -* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows -* Type: null or String - -The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init ` commands. - - - - - - -### See Also - -* [npm scripts](/using-npm/scripts) -* [npm test](/commands/npm-test) -* [npm start](/commands/npm-start) -* [npm restart](/commands/npm-restart) -* [npm stop](/commands/npm-stop) -* [npm config](/commands/npm-config) -* [npm workspaces](/using-npm/workspaces) diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md deleted file mode 100644 index 340dea9684d00..0000000000000 --- a/docs/content/commands/npm-search.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: npm-search -section: 1 -description: Search for packages ---- - -### Synopsis - - - - - -```bash -npm search [search terms ...] - -aliases: find, s, se -``` - - - - - - -Note: This command is unaware of workspaces. - -### Description - -Search the registry for packages matching the search terms. `npm search` -performs a linear, incremental, lexically-ordered search through package -metadata for all files in the registry. If your terminal has color -support, it will further highlight the matches in the results. This can -be disabled with the config item `color` - -Additionally, using the `--searchopts` and `--searchexclude` options -paired with more search terms will include and exclude further patterns. -The main difference between `--searchopts` and the standard search terms -is that the former does not highlight results in the output and you can -use them more fine-grained filtering. Additionally, you can add both of -these to your config to change default search filtering behavior. - -Search also allows targeting of maintainers in search results, by prefixing -their npm username with `=`. - -If a term starts with `/`, then it's interpreted as a regular expression -and supports standard JavaScript RegExp syntax. In this case search will -ignore a trailing `/` . (Note you must escape or quote many regular -expression characters in most shells.) - -### Configuration - - - - -#### `long` - -* Default: false -* Type: Boolean - -Show extended information in `ls`, `search`, and `help-search`. - - - - -#### `json` - -* Default: false -* Type: Boolean - -Whether or not to output JSON data, rather than the normal output. - -* In `npm pkg set` it enables parsing set values with JSON.parse() before - saving them to your `package.json`. - -Not supported by all npm commands. - - - - -#### `color` - -* Default: true unless the NO_COLOR environ is set to something other than '0' -* Type: "always" or Boolean - -If false, never shows colors. If `"always"` then always shows colors. If -true, then only prints color codes for tty file descriptors. - - - - -#### `parseable` - -* Default: false -* Type: Boolean - -Output parseable results from commands that write to standard output. For -`npm search`, this will be tab-separated table format. - - - - -#### `description` - -* Default: true -* Type: Boolean - -Show the description in `npm search` - - - - -#### `searchopts` - -* Default: "" -* Type: String - -Space-separated options that are always passed to search. - - - - -#### `searchexclude` - -* Default: "" -* Type: String - -Space-separated options that limit the results from search. - - - - -#### `registry` - -* Default: "https://registry.npmjs.org/" -* Type: URL - -The base URL of the npm registry. - - - - -#### `prefer-online` - -* Default: false -* Type: Boolean - -If true, staleness checks for cached data will be forced, making the CLI -look for updates immediately even for fresh package data. - - - - -#### `prefer-offline` - -* Default: false -* Type: Boolean - -If true, staleness checks for cached data will be bypassed, but missing data -will be requested from the server. To force full offline mode, use -`--offline`. - - - - -#### `offline` - -* Default: false -* Type: Boolean - -Force offline mode: no network requests will be done during install. To -allow the CLI to fill in missing cache data, see `--prefer-offline`. - - - - - - -### See Also - -* [npm registry](/using-npm/registry) -* [npm config](/commands/npm-config) -* [npmrc](/configuring-npm/npmrc) -* [npm view](/commands/npm-view) -* [npm cache](/commands/npm-cache) -* https://npm.im/npm-registry-fetch diff --git a/docs/content/commands/npm-set-script.md b/docs/content/commands/npm-set-script.md deleted file mode 100644 index 8695b43f14423..0000000000000 --- a/docs/content/commands/npm-set-script.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: npm-set-script -section: 1 -description: Set tasks in the scripts section of package.json ---- - -### Synopsis -An npm command that lets you create a task in the `scripts` section of the `package.json`. - -Deprecated. - - - - - -```bash -npm set-script [