UNPKG

16.6 kBTypeScriptView Raw
1import type {LiteralUnion} from './literal-union';
2import type {JsonObject, JsonValue} from './basic';
3
4declare namespace PackageJson {
5 /**
6 A person who has been involved in creating or maintaining the package.
7 */
8 export type Person =
9 | string
10 | {
11 name: string;
12 url?: string;
13 email?: string;
14 };
15
16 export type BugsLocation =
17 | string
18 | {
19 /**
20 The URL to the package's issue tracker.
21 */
22 url?: string;
23
24 /**
25 The email address to which issues should be reported.
26 */
27 email?: string;
28 };
29
30 export type DirectoryLocations = {
31 [directoryType: string]: JsonValue | undefined;
32
33 /**
34 Location for executable scripts. Sugar to generate entries in the `bin` property by walking the folder.
35 */
36 bin?: string;
37
38 /**
39 Location for Markdown files.
40 */
41 doc?: string;
42
43 /**
44 Location for example scripts.
45 */
46 example?: string;
47
48 /**
49 Location for the bulk of the library.
50 */
51 lib?: string;
52
53 /**
54 Location for man pages. Sugar to generate a `man` array by walking the folder.
55 */
56 man?: string;
57
58 /**
59 Location for test files.
60 */
61 test?: string;
62 };
63
64 export type Scripts = {
65 /**
66 Run **before** the package is published (Also run on local `npm install` without any arguments).
67 */
68 prepublish?: string;
69
70 /**
71 Run both **before** the package is packed and published, and on local `npm install` without any arguments. This is run **after** `prepublish`, but **before** `prepublishOnly`.
72 */
73 prepare?: string;
74
75 /**
76 Run **before** the package is prepared and packed, **only** on `npm publish`.
77 */
78 prepublishOnly?: string;
79
80 /**
81 Run **before** a tarball is packed (on `npm pack`, `npm publish`, and when installing git dependencies).
82 */
83 prepack?: string;
84
85 /**
86 Run **after** the tarball has been generated and moved to its final destination.
87 */
88 postpack?: string;
89
90 /**
91 Run **after** the package is published.
92 */
93 publish?: string;
94
95 /**
96 Run **after** the package is published.
97 */
98 postpublish?: string;
99
100 /**
101 Run **before** the package is installed.
102 */
103 preinstall?: string;
104
105 /**
106 Run **after** the package is installed.
107 */
108 install?: string;
109
110 /**
111 Run **after** the package is installed and after `install`.
112 */
113 postinstall?: string;
114
115 /**
116 Run **before** the package is uninstalled and before `uninstall`.
117 */
118 preuninstall?: string;
119
120 /**
121 Run **before** the package is uninstalled.
122 */
123 uninstall?: string;
124
125 /**
126 Run **after** the package is uninstalled.
127 */
128 postuninstall?: string;
129
130 /**
131 Run **before** bump the package version and before `version`.
132 */
133 preversion?: string;
134
135 /**
136 Run **before** bump the package version.
137 */
138 version?: string;
139
140 /**
141 Run **after** bump the package version.
142 */
143 postversion?: string;
144
145 /**
146 Run with the `npm test` command, before `test`.
147 */
148 pretest?: string;
149
150 /**
151 Run with the `npm test` command.
152 */
153 test?: string;
154
155 /**
156 Run with the `npm test` command, after `test`.
157 */
158 posttest?: string;
159
160 /**
161 Run with the `npm stop` command, before `stop`.
162 */
163 prestop?: string;
164
165 /**
166 Run with the `npm stop` command.
167 */
168 stop?: string;
169
170 /**
171 Run with the `npm stop` command, after `stop`.
172 */
173 poststop?: string;
174
175 /**
176 Run with the `npm start` command, before `start`.
177 */
178 prestart?: string;
179
180 /**
181 Run with the `npm start` command.
182 */
183 start?: string;
184
185 /**
186 Run with the `npm start` command, after `start`.
187 */
188 poststart?: string;
189
190 /**
191 Run with the `npm restart` command, before `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
192 */
193 prerestart?: string;
194
195 /**
196 Run with the `npm restart` command. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
197 */
198 restart?: string;
199
200 /**
201 Run with the `npm restart` command, after `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
202 */
203 postrestart?: string;
204 } & Partial<Record<string, string>>;
205
206 /**
207 Dependencies of the package. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or Git URL.
208 */
209 export type Dependency = Partial<Record<string, string>>;
210
211 /**
212 A mapping of conditions and the paths to which they resolve.
213 */
214 type ExportConditions = { // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
215 [condition: string]: Exports;
216 };
217
218 /**
219 Entry points of a module, optionally with conditions and subpath exports.
220 */
221 export type Exports =
222 | null
223 | string
224 | Array<string | ExportConditions>
225 | ExportConditions;
226
227 /**
228 Import map entries of a module, optionally with conditions and subpath imports.
229 */
230 export type Imports = { // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
231 [key: `#${string}`]: Exports;
232 };
233
234 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
235 export interface NonStandardEntryPoints {
236 /**
237 An ECMAScript module ID that is the primary entry point to the program.
238 */
239 module?: string;
240
241 /**
242 A module ID with untranspiled code that is the primary entry point to the program.
243 */
244 esnext?:
245 | string
246 | {
247 [moduleName: string]: string | undefined;
248 main?: string;
249 browser?: string;
250 };
251
252 /**
253 A hint to JavaScript bundlers or component tools when packaging modules for client side use.
254 */
255 browser?:
256 | string
257 | Partial<Record<string, string | false>>;
258
259 /**
260 Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused.
261
262 [Read more.](https://webpack.js.org/guides/tree-shaking/)
263 */
264 sideEffects?: boolean | string[];
265 }
266
267 export type TypeScriptConfiguration = {
268 /**
269 Location of the bundled TypeScript declaration file.
270 */
271 types?: string;
272
273 /**
274 Version selection map of TypeScript.
275 */
276 typesVersions?: Partial<Record<string, Partial<Record<string, string[]>>>>;
277
278 /**
279 Location of the bundled TypeScript declaration file. Alias of `types`.
280 */
281 typings?: string;
282 };
283
284 /**
285 An alternative configuration for workspaces.
286 */
287 export type WorkspaceConfig = {
288 /**
289 An array of workspace pattern strings which contain the workspace packages.
290 */
291 packages?: WorkspacePattern[];
292
293 /**
294 Designed to solve the problem of packages which break when their `node_modules` are moved to the root workspace directory - a process known as hoisting. For these packages, both within your workspace, and also some that have been installed via `node_modules`, it is important to have a mechanism for preventing the default Yarn workspace behavior. By adding workspace pattern strings here, Yarn will resume non-workspace behavior for any package which matches the defined patterns.
295
296 [Supported](https://classic.yarnpkg.com/blog/2018/02/15/nohoist/) by Yarn.
297 [Not supported](https://github.com/npm/rfcs/issues/287) by npm.
298 */
299 nohoist?: WorkspacePattern[];
300 };
301
302 /**
303 A workspace pattern points to a directory or group of directories which contain packages that should be included in the workspace installation process.
304
305 The patterns are handled with [minimatch](https://github.com/isaacs/minimatch).
306
307 @example
308 `docs` → Include the docs directory and install its dependencies.
309 `packages/*` → Include all nested directories within the packages directory, like `packages/cli` and `packages/core`.
310 */
311 type WorkspacePattern = string;
312
313 export type YarnConfiguration = {
314 /**
315 If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command-line, set this to `true`.
316
317 Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an app), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line.
318 */
319 flat?: boolean;
320
321 /**
322 Selective version resolutions. Allows the definition of custom package versions inside dependencies without manual edits in the `yarn.lock` file.
323 */
324 resolutions?: Dependency;
325 };
326
327 export type JSPMConfiguration = {
328 /**
329 JSPM configuration.
330 */
331 jspm?: PackageJson;
332 };
333
334 /**
335 Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Containing standard npm properties.
336 */
337 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
338 export interface PackageJsonStandard {
339 /**
340 The name of the package.
341 */
342 name?: string;
343
344 /**
345 Package version, parseable by [`node-semver`](https://github.com/npm/node-semver).
346 */
347 version?: string;
348
349 /**
350 Package description, listed in `npm search`.
351 */
352 description?: string;
353
354 /**
355 Keywords associated with package, listed in `npm search`.
356 */
357 keywords?: string[];
358
359 /**
360 The URL to the package's homepage.
361 */
362 homepage?: LiteralUnion<'.', string>;
363
364 /**
365 The URL to the package's issue tracker and/or the email address to which issues should be reported.
366 */
367 bugs?: BugsLocation;
368
369 /**
370 The license for the package.
371 */
372 license?: string;
373
374 /**
375 The licenses for the package.
376 */
377 licenses?: Array<{
378 type?: string;
379 url?: string;
380 }>;
381
382 author?: Person;
383
384 /**
385 A list of people who contributed to the package.
386 */
387 contributors?: Person[];
388
389 /**
390 A list of people who maintain the package.
391 */
392 maintainers?: Person[];
393
394 /**
395 The files included in the package.
396 */
397 files?: string[];
398
399 /**
400 Resolution algorithm for importing ".js" files from the package's scope.
401
402 [Read more.](https://nodejs.org/api/esm.html#esm_package_json_type_field)
403 */
404 type?: 'module' | 'commonjs';
405
406 /**
407 The module ID that is the primary entry point to the program.
408 */
409 main?: string;
410
411 /**
412 Subpath exports to define entry points of the package.
413
414 [Read more.](https://nodejs.org/api/packages.html#subpath-exports)
415 */
416 exports?: Exports;
417
418 /**
419 Subpath imports to define internal package import maps that only apply to import specifiers from within the package itself.
420
421 [Read more.](https://nodejs.org/api/packages.html#subpath-imports)
422 */
423 imports?: Imports;
424
425 /**
426 The executable files that should be installed into the `PATH`.
427 */
428 bin?:
429 | string
430 | Partial<Record<string, string>>;
431
432 /**
433 Filenames to put in place for the `man` program to find.
434 */
435 man?: string | string[];
436
437 /**
438 Indicates the structure of the package.
439 */
440 directories?: DirectoryLocations;
441
442 /**
443 Location for the code repository.
444 */
445 repository?:
446 | string
447 | {
448 type: string;
449 url: string;
450
451 /**
452 Relative path to package.json if it is placed in non-root directory (for example if it is part of a monorepo).
453
454 [Read more.](https://github.com/npm/rfcs/blob/latest/implemented/0010-monorepo-subdirectory-declaration.md)
455 */
456 directory?: string;
457 };
458
459 /**
460 Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point.
461 */
462 scripts?: Scripts;
463
464 /**
465 Is used to set configuration parameters used in package scripts that persist across upgrades.
466 */
467 config?: JsonObject;
468
469 /**
470 The dependencies of the package.
471 */
472 dependencies?: Dependency;
473
474 /**
475 Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling.
476 */
477 devDependencies?: Dependency;
478
479 /**
480 Dependencies that are skipped if they fail to install.
481 */
482 optionalDependencies?: Dependency;
483
484 /**
485 Dependencies that will usually be required by the package user directly or via another dependency.
486 */
487 peerDependencies?: Dependency;
488
489 /**
490 Indicate peer dependencies that are optional.
491 */
492 peerDependenciesMeta?: Partial<Record<string, {optional: true}>>;
493
494 /**
495 Package names that are bundled when the package is published.
496 */
497 bundledDependencies?: string[];
498
499 /**
500 Alias of `bundledDependencies`.
501 */
502 bundleDependencies?: string[];
503
504 /**
505 Engines that this package runs on.
506 */
507 engines?: {
508 [EngineName in 'npm' | 'node' | string]?: string;
509 };
510
511 /**
512 @deprecated
513 */
514 engineStrict?: boolean;
515
516 /**
517 Operating systems the module runs on.
518 */
519 os?: Array<LiteralUnion<
520 | 'aix'
521 | 'darwin'
522 | 'freebsd'
523 | 'linux'
524 | 'openbsd'
525 | 'sunos'
526 | 'win32'
527 | '!aix'
528 | '!darwin'
529 | '!freebsd'
530 | '!linux'
531 | '!openbsd'
532 | '!sunos'
533 | '!win32',
534 string
535 >>;
536
537 /**
538 CPU architectures the module runs on.
539 */
540 cpu?: Array<LiteralUnion<
541 | 'arm'
542 | 'arm64'
543 | 'ia32'
544 | 'mips'
545 | 'mipsel'
546 | 'ppc'
547 | 'ppc64'
548 | 's390'
549 | 's390x'
550 | 'x32'
551 | 'x64'
552 | '!arm'
553 | '!arm64'
554 | '!ia32'
555 | '!mips'
556 | '!mipsel'
557 | '!ppc'
558 | '!ppc64'
559 | '!s390'
560 | '!s390x'
561 | '!x32'
562 | '!x64',
563 string
564 >>;
565
566 /**
567 If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally.
568
569 @deprecated
570 */
571 preferGlobal?: boolean;
572
573 /**
574 If set to `true`, then npm will refuse to publish it.
575 */
576 private?: boolean;
577
578 /**
579 A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
580 */
581 publishConfig?: PublishConfig;
582
583 /**
584 Describes and notifies consumers of a package's monetary support information.
585
586 [Read more.](https://github.com/npm/rfcs/blob/latest/accepted/0017-add-funding-support.md)
587 */
588 funding?: string | {
589 /**
590 The type of funding.
591 */
592 type?: LiteralUnion<
593 | 'github'
594 | 'opencollective'
595 | 'patreon'
596 | 'individual'
597 | 'foundation'
598 | 'corporation',
599 string
600 >;
601
602 /**
603 The URL to the funding page.
604 */
605 url: string;
606 };
607
608 /**
609 Used to configure [npm workspaces](https://docs.npmjs.com/cli/using-npm/workspaces) / [Yarn workspaces](https://classic.yarnpkg.com/docs/workspaces/).
610
611 Workspaces allow you to manage multiple packages within the same repository in such a way that you only need to run your install command once in order to install all of them in a single pass.
612
613 Please note that the top-level `private` property of `package.json` **must** be set to `true` in order to use workspaces.
614 */
615 workspaces?: WorkspacePattern[] | WorkspaceConfig;
616 }
617
618 /**
619 Type for [`package.json` file used by the Node.js runtime](https://nodejs.org/api/packages.html#nodejs-packagejson-field-definitions).
620 */
621 export type NodeJsStandard = {
622 /**
623 Defines which package manager is expected to be used when working on the current project. It can set to any of the [supported package managers](https://nodejs.org/api/corepack.html#supported-package-managers), and will ensure that your teams use the exact same package manager versions without having to install anything else than Node.js.
624
625 __This field is currently experimental and needs to be opted-in; check the [Corepack](https://nodejs.org/api/corepack.html) page for details about the procedure.__
626
627 @example
628 ```json
629 {
630 "packageManager": "<package manager name>@<version>"
631 }
632 ```
633 */
634 packageManager?: string;
635 };
636
637 export type PublishConfig = {
638 /**
639 Additional, less common properties from the [npm docs on `publishConfig`](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#publishconfig).
640 */
641 [additionalProperties: string]: JsonValue | undefined;
642
643 /**
644 When publishing scoped packages, the access level defaults to restricted. If you want your scoped package to be publicly viewable (and installable) set `--access=public`. The only valid values for access are public and restricted. Unscoped packages always have an access level of public.
645 */
646 access?: 'public' | 'restricted';
647
648 /**
649 The base URL of the npm registry.
650
651 Default: `'https://registry.npmjs.org/'`
652 */
653 registry?: string;
654
655 /**
656 The tag to publish the package under.
657
658 Default: `'latest'`
659 */
660 tag?: string;
661 };
662}
663
664/**
665Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
666
667@category File
668*/
669export type PackageJson =
670JsonObject &
671PackageJson.NodeJsStandard &
672PackageJson.PackageJsonStandard &
673PackageJson.NonStandardEntryPoints &
674PackageJson.TypeScriptConfiguration &
675PackageJson.YarnConfiguration &
676PackageJson.JSPMConfiguration;