diff --git a/.gitignore b/.gitignore index d65dfb740..f96f6a30d 100644 --- 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 index 9ea6ed55c..213fa46ca 100644 --- a/docs/commands/add.md +++ b/docs/commands/add.md @@ -5,41 +5,71 @@ title: modular add # `modular add ` -Adds a new package by creating a new workspace at `packages/`, -omitting the scope if the package is +Adds a new package by creating a new package at the workspace located at +`packages/`, omitting the scope if the package is [scoped](https://docs.npmjs.com/cli/v8/using-npm/scope). If `--path ` -is specified, create the workspace at `/`. +is specified, the command creates the workspace at `/`. (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 `: 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 index 99bcdc674..285760e39 100644 --- 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 index bfb63e90c..4772e379b 100644 --- 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 index 1368026d1..43e3c6117 100644 --- 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 index 79856d824..57900a3b3 100644 --- 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 new file mode 100644 index 000000000..a42f27106 --- /dev/null +++ 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). diff --git a/docs/package-types/esm-view.md b/docs/package-types/esm-view.md new file mode 100644 index 000000000..bcb732a02 --- /dev/null +++ b/docs/package-types/esm-view.md @@ -0,0 +1,154 @@ +--- +parent: Package Types +nav_order: 20 +title: esm-view +--- + +# ESM View + +Modular `esm-view`s are built with the same Webpack or esbuild configuration and +support the same functionalities as the [`app`](./app.md) type, with the +following essential differences: + +1. They are compiled as + [ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) + +1. All their external `import`s are rewritten to point to an + [ESM CDN](../esm-views/esm-cdn.md). + +1. They don't allow the user to specify a custom `index.html` + +1. They don't include a `public` folder in the build + +1. They expect their entry-point (`src/index.tsx`) to not render to the DOM, but + to export something, typically a React Component. + +The `esm-view` type is used for creating +[micro-frontends](../concepts/microfrontends.md). They typically expect their +entry-point 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 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. + +## Build + +To [build](../commands/build.md) your ESM View for deployment, run: + +```bash +modular build my-esm-view-name +``` + +The resulting output is an optimized site that can be served statically or +imported at run-time using +[dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import). +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, except +for external dependencies that are re-written to an ESM CDN (this behaviour is +[configurable](../configuration.md)). + +### Dynamically loading vs statically serving ESM Views + +The resulting output of an ESM View contains a synthetically-generated +`index.html` file and a `_trampoline.js` loader, which allows an ESM View to be +served like a static website. The JS and CSS bundle are hashed and linked in the +[generated package.json](../esm-views/output-package-manifest.md), that the +loading code can fetch and examine before importing the `esm-view` at runtime. +For example, this is the stucture of a built ESM View on the filesystem: + +``` +/dist/my-esm-view +├── asset-manifest.json +├── index.html +├── package.json +└── static + ├── css + | ├── main.1915b736.css + | └── main.1915b736.css.map + └── js + ├── _trampoline.js + ├── main.bf0399f0.js + └── main.bf0399f0.js.map +``` + +where `/index.html` and `/static/js/_trampoline` are generated to statically +serve the ESM View. It is also possible to load the ESM view dynamically, by +discovering the hashed JS (`/static/js/main.bf0399f0.js`) and CSS +(`/static/css/main.1915b736.css`) entrypoints from the generated +`/package.json`: + +``` +{ + "name": "my-esm-view", + "version": "1.0.0", + "modular": { + "type": "esm-view" + }, + "dependencies": { + "react": "^18.2.0" + }, + "bundledDependencies": [], + "module": "/static/js/main.bf0399f0.js", + "style": "/static/css/main.1915b736.css" +} +``` + +and importing them at run-time (assuming they are served from `baseUrl`): + +```js +const { default: LoadedView } = await import( + /* webpackIgnore: true */ `${baseUrl}/static/js/main.bf0399f0.js` +); +// Render LoadedView with React +``` + +```js +const node = document.head; +const url = `${baseUrl}/static/css/main.1915b736.css`; +// Make sure that the CSS is not already loaded +if (!node.querySelector(`link[href="${url}"]`)) { + node.insertAdjacentHTML( + 'beforeend', + ``, + ); +} +``` + +## Start + +To run your ESM View 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 ESM View with an +additional runtime layer that provides a trampoline module to load the generated +files, plus developer experience functionalities like hot reloading and +on-screen error overlay. Please make sure that your ESM View entry-point exports +a React component as default for this to work. + +## Entry-point + +ESM-Views need an entry-point file located at `src/index.tsx`, which typically +exports a React component as default for the synthetically generated +`index.html` and the `start` command to work. + +## Template + +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](./template.md). + +## ESM View Reference + +For an in-depth reference of how ESM Views work and can be customized, see this +[section](../esm-views). diff --git a/docs/package-types/index.md b/docs/package-types/index.md new file mode 100644 index 000000000..04423e273 --- /dev/null +++ b/docs/package-types/index.md @@ -0,0 +1,31 @@ +--- +title: Package Types +has_children: true +nav_order: 5 +--- + + + + + +# Package types + +Modular can build several different kinds of packages. We refer to each package +type as a Modular type, and each has different features. The table below +summarises the compatibility of each Modular type with Modular commands and +details their unique features. + +| Type | [start](../commands/start.md) | [build](../commands/build.md) | [test](../commands/test.md) | [lint](../commands/lint.md) | Custom index / assets | Bundled | Entry-point | +| --------------------------- | ----------------------------- | ----------------------------- | --------------------------- | --------------------------- | -------------------------- | --------------------- | ------------------------------ | +| [`app`](./app.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `src/index.tsx` | +| [`esm-view`](./esm-view.md) | ✅ | ✅ | ✅ | ✅ | ❌ | ✅† | `src/index.tsx` | +| [`package`](./package.md) | ❌ | ✅ | ✅ | ✅ | **N/A** | ❌ | `main` field of `package.json` | +| [`view`](./view.md) | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | `main` field of `package.json` | +| [`source`](./source.md) | ❌ | ❌ | ✅ | ✅ | **N/A** | **N/A** - never built | **N/A** - never built | +| [`template`](./template.md) | ❌ | ❌ | ✅ | ✅ | Depends on the target type | **N/A** - never built | **N/A** - never built | + +† For ESM Views, external dependencies are rewritten to point to a CDN diff --git a/docs/package-types/package.md b/docs/package-types/package.md new file mode 100644 index 000000000..b2eddfa65 --- /dev/null +++ b/docs/package-types/package.md @@ -0,0 +1,108 @@ +--- +parent: Package Types +nav_order: 30 +title: package +--- + +# Package + +Modular `package`s are generic, publishable libraries with a single entry-point +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. + +## Build + +To [build](../commands/build.md) your package for deployment, run: + +```bash +modular build my-package-name +``` + +The resulting output looks like: + +``` +/dist/ +├── 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](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 +entry-points 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": "", + "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`](../commands/start.md) command fails when invoked on a package. For a +similar type that can be started, see [`view`](./view.md). + +## 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 add`ing a new package sets it as `"./src/index.ts"`, but it's possible +to manually modify it. + +## 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`](./source.md) type instead. + +## Template + +Packages are generated by `modular add` using the +[`modular-template-package`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-package) +[template](./template.md). diff --git a/docs/package-types/source.md b/docs/package-types/source.md new file mode 100644 index 000000000..4a5afb212 --- /dev/null +++ b/docs/package-types/source.md @@ -0,0 +1,42 @@ +--- +parent: Package Types +nav_order: 50 +title: source +--- + +# Source + +Modular `source` packages contain common source code that can be imported from +other packages in the monorepo. Source packages are not meant to be built +themselves; they are meant to be imported directly from other packages in the +monorepository. For this reason, they 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. + +## Build + +Source packages cannot be built; the [`build`](../commands/build.md) command +will ignore them without throwing an error, to allow for selective builds to +still succeed if their dependency graph contains one or more `source` packages. + +## Start + +Source package cannot be started; attempting to do so will cause Modular to +throw an error. + +## Entry-point + +Source packages are imported from their source files directly, so they don't +have the concept of "entry-point". + +## Template + +Sources are generated by `modular add` using the +[`modular-template-source`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-source) +[template](./template.md). diff --git a/docs/concepts/templates.md b/docs/package-types/template.md similarity index 74% rename from docs/concepts/templates.md rename to docs/package-types/template.md index c1f548fea..03192ceb4 100644 --- a/docs/concepts/templates.md +++ b/docs/package-types/template.md @@ -1,9 +1,10 @@ --- -parent: Concepts -title: Modular Templates +parent: Package Types +nav_order: 60 +title: template --- -# Templates +# Template Templates are a special kind of Modular package, defined by the `modular: { type: template, "templateType": "..." }` fields in their @@ -44,12 +45,13 @@ are maintained by the Modular team in the published to the NPM registry. This is a list of default templates, linked to the correspondent type and NPM package: -| Modular type | Template | NPM Package | -| ------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -| app | [modular-template-app](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-app) | [Link](https://www.npmjs.com/package/modular-template-app) | -| esm-view | [modular-template-esm-view](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-esm-view) | [Link](https://www.npmjs.com/package/modular-template-esm-view) | -| package | [modular-template-package](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-package) | [Link](https://www.npmjs.com/package/modular-template-package) | -| view | [modular-template-view](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-view) | [Link](https://www.npmjs.com/package/modular-template-view) | +| Modular type | Template | NPM Package | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | +| [app](./app.md) | [modular-template-app](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-app) | [Link](https://www.npmjs.com/package/modular-template-app) | +| [esm-view](./esm-view.md) | [modular-template-esm-view](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-esm-view) | [Link](https://www.npmjs.com/package/modular-template-esm-view) | +| [package](./package.md) | [modular-template-package](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-package) | [Link](https://www.npmjs.com/package/modular-template-package) | +| [view](./view.md) | [modular-template-view](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-view) | [Link](https://www.npmjs.com/package/modular-template-view) | +| [source](./source.md) | [modular-template-source](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-source) | [Link](https://www.npmjs.com/package/modular-template-source) | # Community templates diff --git a/docs/package-types/view.md b/docs/package-types/view.md new file mode 100644 index 000000000..8b677d221 --- /dev/null +++ b/docs/package-types/view.md @@ -0,0 +1,47 @@ +--- +parent: Package Types +nav_order: 40 +title: view +--- + +# View + +Modular `view`s are Modular [`package`s](./package.md) that, by convention, +export a default React component. They are [created](../commands/add.md) with a +default entry-point is `src/index.tsx` in their `package.json` and they are +built exactly like [`package`](./package.md) 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. + +## Build + +Same as [`package`](./package.md/#build). + +## Start + +To run your package locally on a development server, run +[start](../commands/start.md): + +```bash +modular start my-package-name +``` + +This causes a developer server to run on port 3000, serving the default export +of the package entry-point with an additional runtime layer that provides +developer experience functionalities like hot reloading and on-screen error +overlay. + +## 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 add`ing a new package sets it as `"./src/index.tsx"`, but it's possible +to manually modify it. The entry-point of a View needs to export a React +component as default for the start command to work. + +## Template + +Views are generated by `modular add` using the +[`modular-template-view`](https://github.com/jpmorganchase/modular/tree/main/packages/modular-template-view) +[template](./template.md).