Document package types

docs/commands/add.md

@@ -5,40 +5,69 @@ title: modular add
 
 # `modular add <packageName>`
 
-Adds a new package by creating a new workspace at `packages/<packageName>`,
-omitting the scope if the package is
+Adds a new package by creating a new package at the workspace located at
+`packages/<packageName>`, omitting the scope if the package is
 [scoped](https://docs.npmjs.com/cli/v8/using-npm/scope). If `--path <somePath>`
-is specified, create the workspace at `<somePath>/<packageName>`.
+is specified, the command creates the workspace at `<somePath>/<packageName>`.
 
 (i.e. `modular add my-app` would create a package in `packages/my-app`,
 `modular add @scoped/my-scoped-app` would create a package in
 `packages/my-scoped-app` and `modular add lib-a --path libs` would create a
 package in `libs/lib-a`)
 
-Packages can currently be one of the following types:
+The `modular add` command prompts the user to choose the Modular `type` of the
+package it's about to create. The next section briefly describes the various
+types that can be created by the `modular add` command. For an in-depth
+discussion of the available package types and their characteristics, please see
+[this page](../concepts/package-types.md).
 
-- A standalone `app`. This corresponds to a static Single Page Application (SPA)
-  project in a workspace. Inside this workspace, you can import packages from
-  other workspaces freely, and features like jsx and typechecking work out of
-  the box.
+### Standalone (bundled) package types
 
-- An `esm-view`, which is a package that typically exports a React component by
-  default. ESM Views are built as ES modules that can be `import`ed at runtime
-  by a host to implement a [micro frontend](../concepts/microfrontends.md)
-  architecture or started as a normal standalone application. See also
-  [the view building reference](../esm-views/index.md)
+These package types are built with [Webpack v5](https://webpack.js.org/) or, if
+specified in the [configuration](../configuration.md),
+[esbuild](https://esbuild.github.io/). Modules imported in the source of these
+package types are bundled in the final result (in case of `esm-view`s, only
+local modules get bundled, and external dependencies are rewritten to use an
+external ESM CDN. [This section](../esm-views/index.md) explains the process in
+more depth).
 
-- A `view`, which is a `package` that exports a React component by default. Read
-  more about Views in [this explainer](../concepts/views.md).
+- `app`. This package type corresponds to a static Single Page Application (SPA)
+  project in a workspace. It's possible to specify a custom `index.html` file
+  and public assets in the `public` directory. See
+  [this page](../concepts/package-types.md/#app) for more information about
+  apps.
 
-- A generic JavaScript `package`. You can use this to create a library with an
-  entry point that gets transpiled to Common JS and ES Module format when built.
-  Packages can be [built](../commands/build.md) but not
-  [start](../commands/start.md)ed by Modular.
+- `esm-view`. This package type is an app that gets built as an ES module that
+  can be imported at runtime. `esm-view`s are typically used to implement a
+  [micro-frontend](../concepts/microfrontends.md) architecture. `esm-views`,
+  when [built](./build.md) or [started](./start.md) will also generate a
+  `index.html` file that tries to load the ES Module and render its default
+  export as a React component onto the DOM (standalone mode). See also
+  [the esm-view reference](../esm-views/index.md) for an in-depth introduction.
+
+### Library package types
+
+These package types are either built with
+[Rollup.js](https://rollupjs.org/guide/en/) as CommonJS and ES Modules or, in
+case of `source` modules, they are not built at all. Library package types get
+typically published to NPM (`package` and `view` types) or get imported by other
+packages in the monorepo (`source` type). For this reason, files are transpiled
+separately on build and external dependencies are never "pulled in" (i.e. not
+included in a bundle).
+
+- `package`. This is a generic package with a single entry point. It's normally
+  used to create a publishable library that gets transpiled to CommonJS and ES
+  Module format when built. Packages can be [built](../commands/build.md) but
+  not [start](../commands/start.md)ed by Modular.
+
+- `view`. This is a `package` that exports a default React component. Views are
+  built exactly like `package`s, but, since Modular knows that the default
+  export can be rendered, `view`s can be [`modular start`](../start.md)ed to
+  preview them locally.
 
-- A `source`, which is a shared package that is imported by other packages from
-  source (i.e. directly importing its source), and it's never built standalone
-  or published. This kind of package is never [built](../commands/build.md) or
+- `source`. A shared package that is imported by other package types in the
+  monorepo, directly specifying one or more of its source files. This kind of
+  package can be never [built](../commands/build.md) or
   [start](../commands/start.md)ed by Modular.
 
 ## Options:

docs/concepts/package-types.md

@@ -0,0 +1,229 @@
+---
+title: Types of packages
+parent: Concepts
+---
+
+| Type       | `modular start` | `modular build` | `modular test` | `modular lint` | Custom index / assets      | Bundled                                      | Entrypoint                                                                                                                                                                                                                                                                                                   |
+| ---------- | --------------- | --------------- | -------------- | -------------- | -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `app`      | Yes             | Yes             | Yes            | Yes            | Yes                        | Yes                                          | The compiled bundle will use `src/index.tsx` as an entrypoint and include it in the generated `index.html`                                                                                                                                                                                                   |
+| `esm-view` | Yes             | Yes             | Yes            | Yes            | No                         | Yes + rewriting external dependencies to CDN | The compiled bundle will use `src/index.tsx` as an entrypoint and [link it](../esm-views/output-package-manifest.md) in the output `package.json`; the entrypoint needs to export a default (non-named) React component for `modular start`/ [standalone `index.html`](../esm-views/how-to-build.md) to work |
+| `package`  | No              | Yes             | Yes            | Yes            | N/A                        | No                                           | Whatever is specified in `main` field of `package.json` is used as the entrypoint                                                                                                                                                                                                                            |
+| `view`     | Yes             | Yes             | Yes            | Yes            | N/A                        | No                                           | Whatever is specified in `main` field of `package.json` is used as the entrypoint; needs to default export React component for `modular start` to work                                                                                                                                                       |
+| `source`   | No              | No              | Yes            | Yes            | N/A                        | N/A - never built                            | N/A - don't need the concept of entrypoint since this package is never built                                                                                                                                                                                                                                 |
+| `template` | No              | No              | Yes            | Yes            | Depends on the target type | N/A - never built                            | N/A - don't need the concept of entrypoint since this is a special type of package used by `modular add` which is never built directly                                                                                                                                                                       |
+
+## App
+
+Modular `app`s are TypeScript and React-based Single Page Applications (SPAs)
+built with [Webpack v5](https://webpack.js.org/) (by default) or
+[esbuild](https://esbuild.github.io/) (by turning on `useModularEsbuild` in
+[the configuration](../configuration.md)).
+
+Apps need at least a `public/index.html` file and an entrypoint located in
+`src/index.tsx`, that typically `render`s a React component to the DOM, to work.
+
+Apps support pretty much all the functionalities from
+[Create React App v5](https://create-react-app.dev/docs/custom-templates), with
+some important differences:
+
+- [ejecting](https://create-react-app.dev/docs/available-scripts/#npm-run-eject)
+  is not supported. As an opinionated tool, Modular tries to offer an uniform
+  way of building applications, although feedback on our build configuration is
+  welcome!
+- [template support](../concepts/templates.md) is integrated in the
+  [`modular add`](../commands/add.md) command. Modular templates are not
+  guaranteed to be compatible with CRA templates.
+- Source files are loaded with the more performant
+  [`esbuild-loader`](https://github.com/privatenumber/esbuild-loader) in the
+  Webpack configuration. For this reason, Babel plugins are not supported.
+- [Local proxies](https://create-react-app.dev/docs/proxying-api-requests-in-development/)
+  are supported, but [esbuild mode](../configuration.md) doesn't support the
+  `package.json` `proxy` field. The more flexible
+  [manual proxy configration](https://create-react-app.dev/docs/proxying-api-requests-in-development/#configuring-the-proxy-manually)
+  is supported in both Webpack and esbuild mode.
+
+Apps can be built using [`modular build`](../commands/build.md): the resulting
+output is an optimized site that can be served statically. All code (files in
+`src` plus external dependencies required in the code) are bundled in a single
+blob of code that can be split in different files.
+
+Apps can be started using [`modular start`](../commands/start.md): a developer
+server runs on port 3000, serving the app with an additional runtime layer that
+provides developer experience functionalities like hot reloading and on-screen
+error overlay.
+
+Apps are generated by `modular add` using the
+[`modular-template-app`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-app)
+[template](../concepts/templates.md)
+
+## ESM View
+
+Modular `esm-view`s are similar to `app`s with some essential differences: they
+are compiled as [ES
+Modules(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)]
+and all their external `import`s are rewritten to point to an
+[ESM CDN](../esm-views/esm-cdn.md). Like apps, they are be built with the same
+Webpack or esbuild configuration and support the same functionalities. Unlike
+apps, they don't allow the user to specify a custom `index.html`, they don't
+include a `public` folder in the build and they expect their entrypoint
+(`src/index.tsx`) to not `render` to the DOM, but to export something, typically
+a React Component.
+
+Esm Views are Modular's type of choice to implement the
+[micro-frontend](../concepts/microfrontends.md) pattern. They typically expect
+their entrypoint exports to be
+[dynamically `import`ed at runtime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
+by some other micro-frontend, but can be also
+[served standalone](../esm-views/how-to-build.md) exactly as an `app`, provided
+that they default export a React component that can be rendered to the DOM.
+
+Since the micro-frontend pattern allows different teams to build and serve their
+applications independently and compose them at runtime (parallelizing otherwise
+expensive build operations), third-party dependencies need to be de-duplicated
+across micro-frontends; for this reason, external dependencies are not bundled,
+but they are rewritten to a [configurable ESM CDN](../esm-views/esm-cdn.md) that
+serves them as ES modules on the fly.
+
+Esm Views can be built using [`modular build`](../commands/build.md): the
+resulting output is an optimized site that can be either served statically
+(using a synthetically-generated `index.html` file and a `_trampoline.js`
+loader), or dynamically imported by another ESM view. The JS and CSS
+entrypoints, in the second case, are linked in the
+[generated manifest file](../esm-views/output-package-manifest.md), that the
+loading code can fetch and examine before loading the `esm-view`. When building
+an ESM View, all "local" code (files in `src`) is bundled in a single blob that
+can be split into different files. All external dependencies are rewritten to an
+external CDN by default and don't get bundled, although this behavior is
+[configurable](../configuration.md).
+
+ESM Views are generated by `modular add` using the
+[`modular-template-esm-view`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-esm-view)
+[template](../concepts/templates.md)
+
+## Package
+
+Modular `package`s are generic, publishable libraries with a single entrypoint
+file. They are built with [Rollup.js](https://rollupjs.org/guide/en/) 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. Modular calculates the
+package entrypoint by looking at the `main` field in the package's
+`package.json`; by default, `modular add`ing a new package sets it as
+`"./src/index.ts"`, but it's possible to manually modify it. Packages can be
+[`test`](../commands/test.md)ed and [`built`](../commands/build.md) by Modular
+but, since they don't necessarily export UI functionality, they can't be
+[`start`](../commands/start.md)ed. If you need a piece of publishable UI (React)
+code that can be previewed locally, you should use `view`s.
+
+Packages are generated by `modular add` using the
+[`modular-template-package`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-package)
+[template](../concepts/templates.md)
+
+### Build output
+
+This is what the build output of a Modular `package` 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
+```
+
+Modular transpiles the `package` starting from its entrypoint twice: once with a
+target format of [CommonJS](https://nodejs.org/api/modules.html) in the
+`dist-cjs` directory and once with a target format of
+[ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules),
+in the `dist-es` directory. The output `package.json` links both compiled
+entrypoints respectively in the
+[`main`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#main) and
+[`module`](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md)
+field.
+
+Modular also extracts types from the source and outputs them in the `dist-types`
+directory, linking them in the
+[`typings`](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html)
+manifest field. Here's an example of an output `package.json` generated when
+building a Modular `package`:
+
+```json
+{
+  "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"]
+}
+```
+
+### When to use the "package" type
+
+Modular `package`s are meant to provide re-usable functionality that can be
+published to third-party registries (like
+[the npm registry](https://www.npmjs.com/)) out-of-the-box; to underline this,
+Modular will, for example, refuse to work with packages that have the
+[`private`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#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.
+
+## View
+
+Modular `view`s are Modular `package`s that, by convention, export a default
+React component. They are [created](../commands/add.md) with a default
+entrypoint is `src/index.tsx` in their `package.json` and they are built and
+tested exactly like `package` types. The only difference is that, since `view`s
+should always export a React component, they can be
+[`start`ed](../commands/start.md) to spawn a local developer server and render
+their default export to the DOM.
+
+Views are generated by `modular add` using the
+[`modular-template-view`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-view)
+[template](../concepts/templates.md)
+
+## Source
+
+Modular `source` types are packages that contain only source code in their `src`
+directory; they are meant to be imported directly from other packages in the
+monorepository and can be [`test`ed](../commands/test.md), but not
+[`built`](../commands/build.md) or [`start`ed](../commands/start.md). `source`s
+are useful to factor out some common code that's used in a monorepository and
+doesn't need to be built separately or published to a registry. `source`s can
+also be used to temporarily work around
+[circular dependency errors](../concepts/circular-dependencies.md), although
+their use in this sense is limited and it's always prefereable to factor out the
+common parts of a circular dependency in an additional dependency to break the
+cycle.
+
+Sources are generated by `modular add` using the
+[`modular-template-source`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-source)
+[template](../concepts/templates.md)
+
+## Template
+
+The Modular `template` type is a special type that is never directly created by
+[`modular add`](../commands/add.md), but it's used by it as a blueprint to
+create other packages of various types. An in-depth explanation of templates can
+be found [here](../concepts/templates.md). Templates are created from scratch;
+to find out how to set up one, please follow
+[this guide](../how-to/create-template.md)