Package

Modular packages are generic, publishable libraries with a single entry-point file. They are built with Rollup.js and they are not bundled in a single blob; files required directly or indirectly from the entry point are separately transpiled as CommonJS Modules and ES Modules (although it’s not a 1:1 correspondence: the compilation process typically creates additional files to normalize exports). External dependencies are not included in the compilation output, but they are copied in the output package.json to be eventually consumed by a bundler.

Build

To build your package for deployment, run:

modular build my-package-name

The resulting output looks like:

<modular-root>/dist/<your-package-name>
├── dist-cjs
|  ├── index.js
|  ├── index.js.map
|  ├── index2.js
|  └── index2.js.map
├── dist-es
|  ├── index.js
|  ├── index.js.map
|  ├── index2.js
|  └── index2.js.map
├── dist-types
|  └── index.d.ts
└── package.json

When building a package, Modular transpiles it starting from its entry-point twice: once with a target format of CommonJS in the dist-cjs directory and once with a target format of ES Modules, in the dist-es directory. The output package.json links both compiled entry-points respectively in the main and module field.

Modular also extracts types from the source and outputs them in the dist-types directory, linking them in the typings manifest field. Here’s an example of an output package.json generated when building a Modular package:

{
  "name": "<your-package-name>",
  "private": false,
  "modular": {
    "type": "package"
  },
  "main": "dist-cjs/index.js",
  "version": "1.0.0",
  "module": "dist-es/index.js",
  "typings": "dist-types/index.d.ts",
  "dependencies": {},
  "files": ["dist-cjs", "dist-es", "dist-types", "README.md"]
}

Start

Modular package is a generic type that doesn’t necessarily export an UI Component; for this reason, it can’t be previewed locally, and the start command fails when invoked on a package. For a similar type that can be started, see view.

Entry-point

The entry-point for a package is configurable; Modular discovers it by looking at the main field in the package’s package.json; by default, modular adding a new package sets it as "./src/index.ts", but it’s possible to manually modify it.

When to use the “package” type

Modular packages are meant to provide re-usable functionality that can be published to third-party registries (like the npm registry) out-of-the-box; to underline this, Modular will, for example, refuse to work with packages that have the private field set. You should use packages only when there is a need to consume their build output; if you just need to share some common source code inside your monorepo but you don’t need to publish it externally, you should use the source type instead.

Template

Packages are generated by modular add using the modular-template-package template.