1package npmpackage
2
3import (
4 "strings"
5 "net"
6 "list"
7 "cue.dev/x/npmjs/eslint"
8 "cue.dev/x/npmjs/prettier"
9 "cue.dev/x/npmjs/stylelint"
10 "cue.dev/x/npmjs/ava"
11 "cue.dev/x/semanticrelease"
12 "cue.dev/x/npmjs/jscpd"
13 "cue.dev/x/npmjs/madge"
14 "cue.dev/x/npmjs/nodemon"
15 "cue.dev/x/npmjs/quikrun"
16)
17
18// JSON schema for NPM package.json files
19#Schema: {
20 @jsonschema(schema="http://json-schema.org/draft-07/schema#")
21 _schema
22 _schema: {
23 @jsonschema(id="https://json.schemastore.org/package.json")
24 {[=~"^_"]: _}
25
26 // The name of the package.
27 "name"?: strings.MaxRunes(214) & strings.MinRunes(1)
28
29 // Version must be parsable by node-semver, which is bundled with npm as a dependency.
30 "version"?: string
31
32 // This helps people discover your package, as it's listed in 'npm search'.
33 "description"?: string
34
35 // This helps people discover your package as it's listed in 'npm search'.
36 "keywords"?: [...string]
37
38 // The url to the project homepage.
39 "homepage"?: string
40
41 // The url to your project's issue tracker and / or the email address to which
42 // issues should be reported. These are helpful for people who encounter issues
43 // with your package.
44 "bugs"?: string | {
45 // The url to your project's issue tracker.
46 "url"?: net.AbsURL
47
48 // The email address to which issues should be reported.
49 "email"?: string
50 ...
51 }
52 "license"?: #license
53
54 // DEPRECATED: Instead, use SPDX expressions, like this: { "license": "ISC" } or
55 // { "license": "(MIT OR Apache-2.0)" } see:
56 // 'https://docs.npmjs.com/files/package.json#license'.
57 "licenses"?: [...{
58 "type"?: #license
59 "url"?: net.AbsURL
60 ...
61 }]
62 "author"?: #person
63
64 // A list of people who contributed to this package.
65 "contributors"?: [...#person]
66
67 // A list of people who maintains this package.
68 "maintainers"?: [...#person]
69
70 // The 'files' field is an array of files to include in your project. If you
71 // name a folder in the array, then it will also include the files inside that
72 // folder.
73 "files"?: [...string]
74
75 // The main field is a module ID that is the primary entry point to your program.
76 "main"?: string
77
78 // The "exports" field is used to restrict external access to non-exported
79 // module files, also enables a module to import itself using "name".
80 "exports"?: matchN(1, [
81 #packageExportsEntryPath,
82 close({
83 "."?: #packageExportsEntryOrFallback
84
85 {[=~"^\\./.+"]: #packageExportsEntryOrFallback}
86 }),
87 #packageExportsEntryObject,
88 #packageExportsFallback
89 ])
90
91 // The "imports" field is used to create private mappings that only apply to
92 // import specifiers from within the package itself.
93 "imports"?: close({
94
95 {[=~"^#.+$"]: #packageImportsEntryOrFallback}})
96 "bin"?: string | {[string]: string}
97
98 // When set to "module", the type field allows a package to specify all .js
99 // files within are ES modules. If the "type" field is omitted or set to
100 // "commonjs", all .js files are treated as CommonJS.
101 "type"?: "commonjs" | "module"
102
103 // Set the types property to point to your bundled declaration file.
104 "types"?: string
105
106 // Note that the "typings" field is synonymous with "types", and could be used as well.
107 "typings"?: string
108
109 // The "typesVersions" field is used since TypeScript 3.1 to support features
110 // that were only made available in newer TypeScript versions.
111 "typesVersions"?: [string]: close({
112 // Maps all file paths to the file paths specified in the array.
113 "*"?: [...=~"^[^*]*(?:\\*[^*]*)?$"]
114
115 {[=~"^[^*]+$"]: [...string]}
116
117 {[=~"^[^*]*\\*[^*]*$"]: [...=~"^[^*]*(?:\\*[^*]*)?$"]}
118 })
119
120 // Specify either a single file or an array of filenames to put in place for the
121 // man program to find.
122 "man"?: string | [...string]
123 "directories"?: {
124 // If you specify a 'bin' directory, then all the files in that folder will be
125 // used as the 'bin' hash.
126 "bin"?: string
127
128 // Put markdown files in here. Eventually, these will be displayed nicely, maybe, someday.
129 "doc"?: string
130
131 // Put example scripts in here. Someday, it might be exposed in some clever way.
132 "example"?: string
133
134 // Tell people where the bulk of your library is. Nothing special is done with
135 // the lib folder in any way, but it's useful meta info.
136 "lib"?: string
137
138 // A folder that is full of man pages. Sugar to generate a 'man' array by walking the folder.
139 "man"?: string
140 "test"?: string
141 ...
142 }
143
144 // Specify the place where your code lives. This is helpful for people who want to contribute.
145 "repository"?: string | {
146 "type"?: string
147 "url"?: string
148 "directory"?: string
149 ...
150 }
151 "funding"?: matchN(1, [
152 #fundingUrl,
153 #fundingWay,
154 list.MinItems(1) & list.UniqueItems() & [...matchN(1, [#fundingUrl, #fundingWay])]
155 ])
156
157 // The 'scripts' member is an object hash of script commands that are run at
158 // various times in the lifecycle of your package. The key is the lifecycle
159 // event, and the value is the command to run at that point.
160 "scripts"?: {
161 // Run code quality tools, e.g. ESLint, TSLint, etc.
162 "lint"?: string
163
164 // Run BEFORE the package is published (Also run on local npm install without any arguments).
165 "prepublish"?: string
166
167 // Runs BEFORE the package is packed, i.e. during "npm publish" and "npm pack",
168 // and on local "npm install" without any arguments. This is run AFTER
169 // "prepublish", but BEFORE "prepublishOnly".
170 "prepare"?: string
171
172 // Run BEFORE the package is prepared and packed, ONLY on npm publish.
173 "prepublishOnly"?: string
174
175 // run BEFORE a tarball is packed (on npm pack, npm publish, and when installing git dependencies).
176 "prepack"?: string
177
178 // Run AFTER the tarball has been generated and moved to its final destination.
179 "postpack"?: string
180
181 // Publishes a package to the registry so that it can be installed by name. See
182 // https://docs.npmjs.com/cli/v8/commands/npm-publish
183 "publish"?: string
184 "postpublish"?: #scriptsPublishAfter
185
186 // Run BEFORE the package is installed.
187 "preinstall"?: string
188 "install"?: #scriptsInstallAfter
189 "postinstall"?: #scriptsInstallAfter
190 "preuninstall"?: #scriptsUninstallBefore
191 "uninstall"?: #scriptsUninstallBefore
192
193 // Run AFTER the package is uninstalled.
194 "postuninstall"?: string
195 "preversion"?: #scriptsVersionBefore
196 "version"?: #scriptsVersionBefore
197
198 // Run AFTER bump the package version.
199 "postversion"?: string
200 "pretest"?: #scriptsTest
201 "test"?: #scriptsTest
202 "posttest"?: #scriptsTest
203 "prestop"?: #scriptsStop
204 "stop"?: #scriptsStop
205 "poststop"?: #scriptsStop
206 "prestart"?: #scriptsStart
207 "start"?: #scriptsStart
208 "poststart"?: #scriptsStart
209 "prerestart"?: #scriptsRestart
210 "restart"?: #scriptsRestart
211 "postrestart"?: #scriptsRestart
212
213 // Start dev server to serve application files
214 "serve"?: string
215 {[!~"^(lint|prepublish|prepare|prepublishOnly|prepack|postpack|publish|postpublish|preinstall|install|postinstall|preuninstall|uninstall|postuninstall|preversion|version|postversion|pretest|test|posttest|prestop|stop|poststop|prestart|start|poststart|prerestart|restart|postrestart|serve)$"]: string}
216 }
217
218 // A 'config' hash can be used to set configuration parameters used in package
219 // scripts that persist across upgrades.
220 "config"?: {...}
221 "dependencies"?: #dependency
222 "devDependencies"?: #devDependency
223 "optionalDependencies"?: #optionalDependency
224 "peerDependencies"?: #peerDependency
225 "peerDependenciesMeta"?: #peerDependencyMeta
226
227 // Array of package names that will be bundled when publishing the package.
228 "bundleDependencies"?: matchN(1, [[...string], bool])
229
230 // DEPRECATED: This field is honored, but "bundleDependencies" is the correct
231 // field name. Ignored if "bundleDependencies" is also present.
232 "bundledDependencies"?: matchN(1, [[...string], bool])
233
234 // Resolutions is used to support selective version resolutions using yarn,
235 // which lets you define custom package versions or ranges inside your
236 // dependencies. For npm, use overrides instead. See:
237 // https://yarnpkg.com/configuration/manifest#resolutions
238 "resolutions"?: {...}
239
240 // Overrides is used to support selective version overrides using npm, which
241 // lets you define custom package versions or ranges inside your dependencies.
242 // For yarn, use resolutions instead. See:
243 // https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides
244 "overrides"?: {...}
245
246 // Defines which package manager is expected to be used when working on the
247 // current project. This field is currently experimental and needs to be
248 // opted-in; see https://nodejs.org/api/corepack.html
249 "packageManager"?: matchN(1, [=~"(npm|pnpm|yarn|bun|aube|nub)@\\d+\\.\\d+\\.\\d+(-.+)?", "bun"])
250 "engines"?: {
251 "node"?: string
252
253 // Specifies which JavaScript runtimes (like Node.js, Deno, Bun) are supported.
254 // Values should use WinterCG Runtime Keys (see
255 // https://runtime-keys.proposal.wintercg.org/).
256 "runtime"?: matchN(1, [#runtimeEngineDependency, [...#runtimeEngineDependency]])
257 {[!~"^(node|runtime)$"]: string}
258 }
259
260 // Defines which tools and versions are expected to be used when Volta is installed.
261 "volta"?: {
262 // The value of that entry should be a path to another JSON file which also has a "volta" section
263 "extends"?: string
264
265 {[=~"(node|npm|pnpm|yarn)"]: string}
266 ...
267 }
268 "engineStrict"?: bool
269
270 // Specify which operating systems your module will run on.
271 "os"?: [...string]
272
273 // Specify that your code only runs on certain cpu architectures.
274 "cpu"?: [...string]
275
276 // Define the runtime and package manager for developing the current project.
277 "devEngines"?: {
278 // Specifies which operating systems are supported for development
279 "os"?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
280
281 // Specifies which CPU architectures are supported for development
282 "cpu"?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
283
284 // Specifies which C standard libraries are supported for development
285 "libc"?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
286
287 // Specifies which JavaScript runtimes (like Node.js, Deno, Bun) are supported
288 // for development. Values should use WinterCG Runtime Keys (see
289 // https://runtime-keys.proposal.wintercg.org/)
290 "runtime"?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
291
292 // Specifies which package managers are supported for development
293 "packageManager"?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
294 ...
295 }
296
297 // DEPRECATED: This option used to trigger an npm warning, but it will no longer
298 // warn. It is purely there for informational purposes. It is now recommended
299 // that you install any binaries as local devDependencies wherever possible.
300 "preferGlobal"?: bool
301
302 // If set to true, then npm will refuse to publish it.
303 "private"?: matchN(1, [bool, "false" | "true"])
304 "publishConfig"?: {
305 "access"?: "public" | "restricted"
306 "tag"?: string
307 "registry"?: net.AbsURL
308 "provenance"?: bool
309 ...
310 }
311 "dist"?: {
312 "shasum"?: string
313 "tarball"?: string
314 ...
315 }
316 "readme"?: string
317
318 // An ECMAScript module ID that is the primary entry point to your program.
319 "module"?: string
320
321 // A module ID with untranspiled code that is the primary entry point to your program.
322 "esnext"?: string | {
323 "main"?: string
324 "browser"?: string
325 {[!~"^(main|browser)$"]: string}
326 }
327
328 // Allows packages within a directory to depend on one another using direct
329 // linking of local files. Additionally, dependencies within a workspace are
330 // hoisted to the workspace root when possible to reduce duplication. Note:
331 // It's also a good idea to set "private" to true when using this feature.
332 "workspaces"?: matchN(>=1, [
333 [...string],
334 {
335 // Workspace package paths. Glob patterns are supported.
336 "packages"?: [...string]
337
338 // Packages to block from hoisting to the workspace root. Currently only supported in Yarn only.
339 "nohoist"?: [...string]
340 ...
341 }
342 ])
343 "jspm"?: _schema
344 "eslintConfig"?: eslint.#Schema
345 "prettier"?: prettier.#Schema
346 "stylelint"?: stylelint.#Schema
347 "ava"?: ava.#Schema
348 "release"?: semanticrelease.#Schema
349 "jscpd"?: jscpd.#Schema
350 "madge"?: madge.#Schema
351 "nodemonConfig"?: nodemon.#Schema
352 "quikrun"?: quikrun.#Schema
353
354 // Defines pnpm specific configuration.
355 "pnpm"?: close({
356 // Used to override any dependency in the dependency graph.
357 "overrides"?: {...}
358
359 // Used to extend the existing package definitions with additional information.
360 "packageExtensions"?: close({
361
362 {
363 [=~"^.+$"]: close({
364 "dependencies"?: #dependency
365 "optionalDependencies"?: #optionalDependency
366 "peerDependencies"?: #peerDependency
367 "peerDependenciesMeta"?: #peerDependencyMeta
368 })
369 }})
370 "peerDependencyRules"?: close({
371 // pnpm will not print warnings about missing peer dependencies from this list.
372 "ignoreMissing"?: [...string]
373
374 // Unmet peer dependency warnings will not be printed for peer dependencies of the specified range.
375 "allowedVersions"?: {...}
376
377 // Any peer dependency matching the pattern will be resolved from any version,
378 // regardless of the range specified in "peerDependencies".
379 "allowAny"?: [...string]
380 })
381
382 // A list of dependencies to run builds for.
383 "neverBuiltDependencies"?: [...string]
384
385 // A list of package names that are allowed to be executed during installation.
386 "onlyBuiltDependencies"?: [...string]
387
388 // Specifies a JSON file that lists the only packages permitted to run
389 // installation scripts during the pnpm install process.
390 "onlyBuiltDependenciesFile"?: string
391
392 // A list of package names that should not be built during installation.
393 "ignoredBuiltDependencies"?: [...string]
394
395 // A list of deprecated versions that the warnings are suppressed.
396 "allowedDeprecatedVersions"?: {...}
397
398 // A list of dependencies that are patched.
399 "patchedDependencies"?: {...}
400
401 // When true, installation won't fail if some of the patches from the
402 // "patchedDependencies" field were not applied.
403 "allowNonAppliedPatches"?: bool
404
405 // When true, installation won't fail if some of the patches from the
406 // "patchedDependencies" field were not applied.
407 "allowUnusedPatches"?: bool
408 "updateConfig"?: close({
409 // A list of packages that should be ignored when running "pnpm outdated" or "pnpm update --latest".
410 "ignoreDependencies"?: [...string]
411 })
412
413 // Configurational dependencies are installed before all the other types of
414 // dependencies (before 'dependencies', 'devDependencies',
415 // 'optionalDependencies').
416 "configDependencies"?: {...}
417 "auditConfig"?: close({
418 // A list of CVE IDs that will be ignored by "pnpm audit".
419 "ignoreCves"?: [...=~"^CVE-\\d{4}-\\d{4,7}$"]
420
421 // A list of GHSA Codes that will be ignored by "pnpm audit".
422 "ignoreGhsas"?: [...=~"^GHSA(-[23456789cfghjmpqrvwx]{4}){3}$"]
423 })
424
425 // A list of scripts that must exist in each project.
426 "requiredScripts"?: [...string]
427
428 // Specifies architectures for which you'd like to install optional
429 // dependencies, even if they don't match the architecture of the system
430 // running the install.
431 "supportedArchitectures"?: close({
432 "os"?: [...string]
433 "cpu"?: [...string]
434 "libc"?: [...string]
435 })
436
437 // A list of optional dependencies that the install should be skipped.
438 "ignoredOptionalDependencies"?: [...string]
439 "executionEnv"?: close({
440 // Specifies which exact Node.js version should be used for the project's runtime.
441 "nodeVersion"?: string
442 })
443 })
444
445 // Defines the StackBlitz configuration for the project.
446 "stackblitz"?: close({
447 // StackBlitz automatically installs npm dependencies when opening a project.
448 "installDependencies"?: bool
449
450 // A terminal command to be executed when opening the project, after installing npm dependencies.
451 "startCommand"?: bool | string
452
453 // The compileTrigger option controls how file changes in the editor are written
454 // to the WebContainers in-memory filesystem.
455 "compileTrigger"?: "auto" | "keystroke" | "save"
456
457 // A map of default environment variables that will be set in each top-level shell process.
458 "env"?: {...}
459 })
460
461 // Records which dependencies are permitted to run install scripts (preinstall,
462 // install, postinstall, and prepare for non-registry sources). Maintained via
463 // the "npm approve-scripts" command, which enforces a default-deny policy:
464 // install scripts for any dependency without a matching entry are silently
465 // skipped. Keys are package identifiers — either name-only (e.g. "pkg") or
466 // pinned with a version (e.g. "pkg@1.2.3"); by default entries are pinned so
467 // approval is version-specific. A value of true allows the dependency's
468 // install scripts to run, while false explicitly denies them (existing false
469 // entries are never silently overridden).
470 "allowScripts"?: [string]: bool
471
472 // Provides hints to the Webpack compiler, denoting which files in your project
473 // are "pure" and therefore safe to prune if unused.
474 "sideEffects"?: matchN(1, [bool, list.UniqueItems() & [...string]])
475 ...
476
477 // Dependencies are specified with a simple hash of package name to version
478 // range. The version range is a string which has one or more space-separated
479 // descriptors. Dependencies can also be identified with a tarball or git URL.
480 #dependency: [string]: string
481
482 // Specifies dependencies that are required for the development and testing of
483 // the project. These dependencies are not needed in the production
484 // environment.
485 #devDependency: [string]: string
486
487 // Specifies requirements for development environment components such as
488 // operating systems, runtimes, or package managers. Used to ensure consistent
489 // development environments across the team.
490 #devEngineDependency: {
491 // The name of the dependency, with allowed values depending on the parent field
492 "name"!: string
493
494 // The version range for the dependency
495 "version"?: string
496
497 // What action to take if validation fails
498 "onFail"?: "ignore" | "warn" | "error" | "download"
499 ...
500 }
501
502 // URL to a website with details about how to fund the package.
503 #fundingUrl: net.AbsURL
504
505 // Used to inform about ways to help fund development of the package.
506 #fundingWay: close({
507 "url"!: #fundingUrl
508
509 // The type of funding or the platform through which funding can be provided,
510 // e.g. patreon, opencollective, tidelift or github.
511 "type"?: string
512 })
513
514 #license: matchN(>=1, [
515 string,
516 "AGPL-3.0-only" |
517 "Apache-2.0" |
518 "BSD-2-Clause" |
519 "BSD-3-Clause" |
520 "BSL-1.0" |
521 "CC0-1.0" |
522 "CDDL-1.0" |
523 "CDDL-1.1" |
524 "EPL-1.0" |
525 "EPL-2.0" |
526 "GPL-2.0-only" |
527 "GPL-3.0-only" |
528 "ISC" |
529 "LGPL-2.0-only" |
530 "LGPL-2.1-only" |
531 "LGPL-2.1-or-later" |
532 "LGPL-3.0-only" |
533 "LGPL-3.0-or-later" |
534 "MIT" |
535 "MPL-2.0" |
536 "MS-PL" |
537 "UNLICENSED",
538 ])
539
540 // Specifies dependencies that are optional for your project. These dependencies
541 // are attempted to be installed during the npm install process, but if they
542 // fail to install, the installation process will not fail.
543 #optionalDependency: [string]: string
544
545 #packageExportsEntry: matchN(1, [#packageExportsEntryPath, #packageExportsEntryObject])
546
547 // Used to specify conditional exports, note that Conditional exports are
548 // unsupported in older environments, so it's recommended to use the fallback
549 // array option if support for those environments is a concern.
550 #packageExportsEntryObject: close({
551 "require"?: #packageExportsEntryOrFallback
552 "import"?: #packageExportsEntryOrFallback
553 "module-sync"?: #packageExportsEntryOrFallback
554 "node"?: #packageExportsEntryOrFallback
555 "default"?: #packageExportsEntryOrFallback
556 "types"?: #packageExportsEntryOrFallback
557
558 {[=~"^[^.0-9]+$"]: #packageExportsEntryOrFallback}
559
560 {[=~"^types@.+$"]: #packageExportsEntryOrFallback}
561 })
562
563 #packageExportsEntryOrFallback: matchN(1, [#packageExportsEntry, #packageExportsFallback])
564
565 // The module path that is resolved when this specifier is imported. Set to
566 // `null` to disallow importing this module.
567 #packageExportsEntryPath: null | =~"^\\./"
568
569 // Used to allow fallbacks in case this environment doesn't support the preceding entries.
570 #packageExportsFallback: [...#packageExportsEntry]
571
572 #packageImportsEntry: matchN(1, [#packageImportsEntryPath, #packageImportsEntryObject])
573
574 // Used to specify conditional exports, note that Conditional exports are
575 // unsupported in older environments, so it's recommended to use the fallback
576 // array option if support for those environments is a concern.
577 #packageImportsEntryObject: close({
578 "require"?: #packageImportsEntryOrFallback
579 "import"?: #packageImportsEntryOrFallback
580 "node"?: #packageImportsEntryOrFallback
581 "default"?: #packageImportsEntryOrFallback
582 "types"?: #packageImportsEntryOrFallback
583
584 {[=~"^[^.0-9]+$"]: #packageImportsEntryOrFallback}
585
586 {[=~"^types@.+$"]: #packageImportsEntryOrFallback}
587 })
588
589 #packageImportsEntryOrFallback: matchN(1, [#packageImportsEntry, #packageImportsFallback])
590
591 // The module path that is resolved when this specifier is imported. Set to
592 // `null` to disallow importing this module.
593 #packageImportsEntryPath: null | string
594
595 // Used to allow fallbacks in case this environment doesn't support the preceding entries.
596 #packageImportsFallback: [...#packageImportsEntry]
597
598 // Specifies dependencies that are required by the package but are expected to
599 // be provided by the consumer of the package.
600 #peerDependency: [string]: string
601
602 // When a user installs your package, warnings are emitted if packages specified
603 // in "peerDependencies" are not already installed. The "peerDependenciesMeta"
604 // field serves to provide more information on how your peer dependencies are
605 // utilized. Most commonly, it allows peer dependencies to be marked as
606 // optional. Metadata for this field is specified with a simple hash of the
607 // package name to a metadata object.
608 #peerDependencyMeta: [string]: {
609 // Specifies that this peer dependency is optional and should not be installed automatically.
610 "optional"?: bool
611 ...
612 }
613
614 // A person who has been involved in creating or maintaining this package.
615 #person: string | {
616 "name"!: string
617 "url"?: net.AbsURL
618 "email"?: string
619 ...
620 }
621
622 // Specifies a supported JavaScript runtime.
623 #runtimeEngineDependency: {
624 // The runtime name
625 "name"!: string
626
627 // The version range for the runtime
628 "version"?: string
629
630 // What action to take if runtime validation fails
631 "onFail"?: "ignore" | "warn" | "error" | "download"
632 ...
633 }
634
635 // Run AFTER the package is installed.
636 #scriptsInstallAfter: string
637
638 // Run AFTER the package is published.
639 #scriptsPublishAfter: string
640
641 // Run by the 'npm restart' command. Note: 'npm restart' will run the stop and
642 // start scripts if no restart script is provided.
643 #scriptsRestart: string
644
645 // Run by the 'npm start' command.
646 #scriptsStart: string
647
648 // Run by the 'npm stop' command.
649 #scriptsStop: string
650
651 // Run by the 'npm test' command.
652 #scriptsTest: string
653
654 // Run BEFORE the package is uninstalled.
655 #scriptsUninstallBefore: string
656
657 // Run BEFORE bump the package version.
658 #scriptsVersionBefore: string
659 }
660}