Document package types (#2246)

* Start documenting package types * Describe App and ESM View types * Packages * Views, sources and templates * Link add command page * Link package types in index * Update docs/commands/add.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Link esm-views section in add page * Update docs/commands/add.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Link app section for more info * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Clarify manifest -> package.json + fix incorrect description * Add reasons why we don't support things * Disambiguate words * Phrase 'default export' concept better * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Update docs/commands/add.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Reword tricky sentence * Update docs/commands/add.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <sam.brown@jpmorgan.com> * Split long sentence * Add all package types to configuration docs * Various typos * Split packge types and move template page * Fix links to package types and fix table layout * Slim down table * build/start/entrypoint/template sections * Fix configuration * Remove list of types in documentation Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>
jpmorganchase · Jan 10, 2023 · aaaa5ee · aaaa5ee
1 parent 2624def
commit aaaa5ee
Show file tree

Hide file tree

Showing 13 changed files with 542 additions and 84 deletions.
diff --git a/.gitignore b/.gitignore
@@ -53,3 +53,9 @@ yarn-error.log*
 .tsbuildinfo
 *.tsbuildinfo
 
+# Local Jekyll preview of docs
+docs/_site
+docs/.bundle
+docs/vendor
+docs/Gemfile*
+
diff --git a/docs/commands/add.md b/docs/commands/add.md
@@ -5,41 +5,71 @@ 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](../package-types/index.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`](../package-types/app.md). 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](../package-types/#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`](../package-types/esm-view.md). 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.
 
-- 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
-  [start](../commands/start.md)ed by Modular.
+### 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`](../package-types/package.md). 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`](../package-types/view.md). 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.
+
+- [`source`](../package-types/source.md). 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:
 
@@ -55,4 +85,4 @@ of the root `package.json`, the command will fail
 
 `--template <templateName>`: Use the package `templateName` from the repository
 or the registry as a template for the new package. Find more information about
-Modular templates [in this page](../concepts/templates.md)
+Modular templates [in this page](../package-types/template.md)
diff --git a/docs/concepts/versioning.md b/docs/concepts/versioning.md
@@ -5,18 +5,11 @@ parent: Concepts
 
 # Version Control in a Modular Repository
 
-Modular's primary focus is on the build & testing of your packages and
-applications, it's not concerned with how you run CI or version the artefacts
-built by it.
-
-There's a multitude of packages and tools out there which you can use to version
-the packages within your repository - some of the biggest of these are
-
-- [`changesets`](https://github.com/atlassian/changesets) - a tool written by
-  Atlassian which applies changeset files to generate the new versions of
-  packages. This is what modular uses internally for managing package versions
-  when publishing.
-
-- [`lerna`](https://github.com/lerna/lerna/) - another open source tool designed
-  for monorepository management. Lerna is more abstract than changesets when it
-  comes to determining version increments but is still easy to use.
+Modular's primary objective is to provide frictionless
+[build](../commands/build.md) and [test](../commands/test.md) functionality for
+your micro-frontend monorepo.
+
+How you version the built artifacts and run your CI pipelines is up to you, but
+we recommend [`changesets`](https://github.com/atlassian/changesets), a tool
+written by Atlassian which uses changeset files to generate new versions of
+packages.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -115,30 +115,6 @@ _e.g._
 }
 ```
 
-The `package.json#modular.type` can be `"root"`, `"app"`, `"view"` or
-`"package"`.
-
-### `"root"`
-
-This type identifies the root of the project.
-
-### `"view"`
-
-This type identifies modules that export a single React component as their
-default export. `modular` makes these modules available via a dynamically
-generated view map with `modular-views.macro`. Read more about Views in
-[this explainer](/docs/concepts/views.md).
-
-### `"app"`
-
-This type identifies a standalone application that can be started or built.
-
-### `"esm-view"`
-
-This type identifies an ESM view that can be started in standalone mode, built
-and imported dynamically by an host application.
-
-### `"package"`
-
-This type identifies a regular package (e.g. a library that can be used by other
-`"view"` or `"app"` modules).
+The `package.json#modular.type` can be `"root"`, `"app"`, `"view"`,
+`"esm-view"`, `"source"`, `"template"` or `"package"`. Read more about Modular
+types in [this explainer](/docs/package-types).
diff --git a/docs/how-to/create-template.md b/docs/how-to/create-template.md
@@ -6,10 +6,10 @@ title: Create Template
 
 # Create a Modular Template
 
-To create a [Modular Template](../concepts/templates.md), start with any Modular
-package type for which you want to create a template for (`app`, `package`,
-etc). The package's contents will be copied into any new package created using
-the template.
+To create a [Modular Template](../package-types/template.md), start with any
+Modular package type for which you want to create a template for (`app`,
+`package`, etc). The package's contents will be copied into any new package
+created using the template.
 
 To convert the package into a template, make the following changes to the
 package's package.json:

diff --git a/docs/index.md b/docs/index.md
@@ -29,7 +29,8 @@ See the [compatibility page](./compatibility.md).
 Bootstraps a new project, configured to use
 [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/).
 
-This also creates a workspace named 'app' which is a new modular app written in
+This also creates a workspace named 'app' which is a new
+[modular app](./package-types) written in
 [TypeScript](https://www.typescriptlang.org/).
 
 It supports three flags:
@@ -42,20 +43,20 @@ It supports three flags:
 
 ## Commands
 
-- [`workspace`](./commands/workspace.md)
-- [`check`](./commands/check.md)
 - [`add`](./commands/add.md)
+- [`build`](./commands/build.md)
 - [`start`](./commands/start.md)
 - [`test`](./commands/test.md)
-- [`build`](./commands/build.md)
 - [`typecheck`](./commands/typecheck.md)
 - [`lint`](./commands/lint.md)
+- [`workspace`](./commands/workspace.md)
+- [`check`](./commands/check.md)
 
 ## Concepts
 
 - [Micro-frontends](./concepts/microfrontends.md)
 - [Configuration](./configuration.md)
-- [Templates](./concepts/templates.md)
+- [Package types](./package-types)
 - [Linting](./concepts/linting.md)
 
 ## How to

diff --git a/docs/package-types/app.md b/docs/package-types/app.md
@@ -0,0 +1,68 @@
+---
+parent: Package Types
+nav_order: 10
+title: app
+---
+
+# 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 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](../package-types/template.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.
+
+## Build
+
+To [build](../commands/build.md) your app for deployment, run:
+
+```bash
+modular build my-app-name
+```
+
+The resulting output is an optimized site that can be served statically. All
+code (files in `src` plus external dependencies required in the code) is bundled
+in a single blob of code that can be split in different files.
+
+## Start
+
+To run your app locally on a development server, run
+[start](../commands/start.md):
+
+```bash
+modular start my-app-name
+```
+
+This causes a developer server to run on port 3000, serving the app with an
+additional runtime layer that provides developer experience functionalities like
+hot reloading and on-screen error overlay.
+
+## Entry-point
+
+Apps need an entry-point file located at `src/index.tsx`, which typically uses
+React to render components to the DOM, generated at `public/index.html`.
+
+## Template
+
+Apps are generated by `modular add` using the
+[`modular-template-app`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-app)
+[template](./template.md).