Generate nicer READMEs inside new projects / apps / views / packages

.changeset/odd-bees-speak.md

@@ -0,0 +1,12 @@
+---
+"create-modular-react-app": minor
+"modular-scripts": minor
+"modular-template-app": minor
+"modular-template-esm-view": minor
+"modular-template-package": minor
+"modular-template-source": minor
+"modular-template-view": minor
+---
+
+Generate README inside newly created packages
+Improve root and default workspaces container README

__fixtures__/templates/modular-template-app/README.md

@@ -0,0 +1,39 @@
+# `PackageName__`
+
+This is a [Modular App](https://modular.js.org/package-types/app)
+
+## Build
+
+To [build](https://modular.js.org/commands/build) your app for deployment, run:
+
+```bash
+modular build PackageName__
+```
+
+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](https://modular.js.org/commands/start):
+
+```bash
+modular start PackageName__
+```
+
+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](https://modular.js.org/package-types/template).

__fixtures__/templates/modular-template-filter/README.md

@@ -0,0 +1,39 @@
+# `PackageName__`
+
+This is a [Modular App](https://modular.js.org/package-types/app)
+
+## Build
+
+To [build](https://modular.js.org/commands/build) your app for deployment, run:
+
+```bash
+modular build PackageName__
+```
+
+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](https://modular.js.org/commands/start):
+
+```bash
+modular start PackageName__
+```
+
+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](https://modular.js.org/package-types/template).

__fixtures__/templates/modular-template-no-filter/README.md

@@ -0,0 +1,39 @@
+# `PackageName__`
+
+This is a [Modular App](https://modular.js.org/package-types/app)
+
+## Build
+
+To [build](https://modular.js.org/commands/build) your app for deployment, run:
+
+```bash
+modular build PackageName__
+```
+
+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](https://modular.js.org/commands/start):
+
+```bash
+modular start PackageName__
+```
+
+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](https://modular.js.org/package-types/template).

docs/configuration.md

@@ -46,7 +46,7 @@ module.exports = {
 
 **Default**: `false` - Uses [Webpack](https://webpack.js.org/)
 
-Use esbuild instead of default Webpack. Only affects Views and ESM Views.
+Use esbuild instead of default Webpack. Only affects Apps and ESM Views.
 
 ### **externalCdnTemplate**
 

docs/package-types/esm-view.md

@@ -127,7 +127,7 @@ To run your ESM View locally on a development server, run
 [start](../commands/start.md):
 
 ```bash
-modular start my-app-name
+modular start my-esm-view-name
 ```
 
 This causes a developer server to run on port 3000, serving the ESM View with an

docs/package-types/view.md

@@ -8,7 +8,7 @@ title: 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
+default entry-point of `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
@@ -20,25 +20,24 @@ Same as [`package`](./package.md/#build).
 
 ## Start
 
-To run your package locally on a development server, run
+To run your view locally on a development server, run
 [start](../commands/start.md):
 
 ```bash
-modular start my-package-name
+modular start my-view-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.
+of the View 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.
+The entry-point for a View is configurable; Modular discovers it by looking at
+the `main` field in the View's `package.json`; by default, `modular add`ing a
+new View 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
 

packages/create-modular-react-app/src/__tests__/__snapshots__/cli.test.ts.snap

@@ -11,13 +11,13 @@ exports[`Creating a new modular app via the CLI should create the right tree 1`]
 │  ├─ launch.json #1kk1omt
 │  └─ settings.json #xes41c
 ├─ .yarnrc #1orkcoz
-├─ README.md #1nksyzj
+├─ README.md #5vircs
 ├─ modular
 │  ├─ setupEnvironment.ts #m0s4vb
 │  └─ setupTests.ts #bnjknz
 ├─ package.json
 ├─ packages
-│  ├─ README.md #14bthrh
+│  ├─ README.md #11apaz5
 │  └─ app
 │     ├─ package.json
 │     ├─ public
@@ -52,13 +52,13 @@ exports[`Creating a new modular app via the CLI with --empty should create the r
 │  ├─ launch.json #1kk1omt
 │  └─ settings.json #xes41c
 ├─ .yarnrc #1orkcoz
-├─ README.md #1nksyzj
+├─ README.md #5vircs
 ├─ modular
 │  ├─ setupEnvironment.ts #m0s4vb
 │  └─ setupTests.ts #bnjknz
 ├─ package.json
 ├─ packages
-│  └─ README.md #14bthrh
+│  └─ README.md #11apaz5
 ├─ tsconfig.json #1h72lkd
 └─ yarn.lock"
 `;

packages/create-modular-react-app/src/__tests__/__snapshots__/index.test.ts.snap

@@ -194,13 +194,13 @@ exports[`create-modular-react-app WHEN it sets up a project with prefer Offline
 │  ├─ launch.json #1kk1omt
 │  └─ settings.json #xes41c
 ├─ .yarnrc #1orkcoz
-├─ README.md #1nksyzj
+├─ README.md #5vircs
 ├─ modular
 │  ├─ setupEnvironment.ts #m0s4vb
 │  └─ setupTests.ts #bnjknz
 ├─ package.json
 ├─ packages
-│  ├─ README.md #14bthrh
+│  ├─ README.md #11apaz5
 │  └─ app
 │     ├─ package.json
 │     ├─ public
@@ -418,13 +418,13 @@ exports[`create-modular-react-app WHEN setting a project with defaults should cr
 │  ├─ launch.json #1kk1omt
 │  └─ settings.json #xes41c
 ├─ .yarnrc #1orkcoz
-├─ README.md #1nksyzj
+├─ README.md #5vircs
 ├─ modular
 │  ├─ setupEnvironment.ts #m0s4vb
 │  └─ setupTests.ts #bnjknz
 ├─ package.json
 ├─ packages
-│  ├─ README.md #14bthrh
+│  ├─ README.md #11apaz5
 │  └─ app
 │     ├─ package.json
 │     ├─ public

packages/create-modular-react-app/template/README.md

@@ -1 +1,75 @@
-This is the `README.md` for the whole monorepo.
+This is a monorepository initialised with [Modular](https://modular.js.org/)
+
+## Commands available
+
+- [Add](https://modular.js.org/commands/add/) - Add a new Modular package to the
+  monorepo
+- [Analyze](https://modular.js.org/commands/analyze/) - Analyzes the
+  dependencies of a package from its source code, emitting JSON to `stdout`.
+- [Build](https://modular.js.org/commands/build/) - Search workspaces based on
+  their name field in the `package.json` and build them according to their
+  respective `modular.type`, in order of dependency.
+- [Check](https://modular.js.org/commands/check/) - Check the modular root repo
+  has [Yarn workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/),
+  modular packages are set up properly and check the package tree for issues
+  with dependencies.
+- [Lint](https://modular.js.org/commands/lint/) - Check the diff between the
+  current branch and the remote origin default branch and lint the source files
+  that have changes. In CI, lint the entire codebase.
+- [Start](https://modular.js.org/commands/start/) - Run the selected Modular
+  `app`, `esm-view` or `view` locally.
+- [Test](https://modular.js.org/commands/test/) - Run [Jest](https://jestjs.io/)
+  tests against a selection of Modular packages.
+- [Typecheck](https://modular.js.org/commands/typecheck/) - Report the semantic,
+  syntactic, and declaration type errors found in your code.
+- [Workspace](https://modular.js.org/commands/workspace/) - Prints information
+  about the monorepository to the console. Like
+  [`yarn workspaces info`](https://classic.yarnpkg.com/lang/en/docs/cli/workspaces/#toc-yarn-workspaces-info),
+  but extended with modular metadata about package type and public/private
+  status.
+
+## Package types
+
+| Type                                                         | [start](https://modular.js.org/commands/start/) | [build](https://modular.js.org/commands/build/) | [test](https://modular.js.org/commands/test/) | [lint](https://modular.js.org/commands/lint/) | Custom index / assets      | Bundled               | Entry-point                    |
+| ------------------------------------------------------------ | ----------------------------------------------- | ----------------------------------------------- | --------------------------------------------- | --------------------------------------------- | -------------------------- | --------------------- | ------------------------------ |
+| [`app`](https://modular.js.org/package-types/app/)           | ✅                                              | ✅                                              | ✅                                            | ✅                                            | ✅                         | ✅                    | `src/index.tsx`                |
+| [`esm-view`](https://modular.js.org/package-types/esm-view/) | ✅                                              | ✅                                              | ✅                                            | ✅                                            | ❌                         | ✅†                   | `src/index.tsx`                |
+| [`package`](https://modular.js.org/package-types/package/)   | ❌                                              | ✅                                              | ✅                                            | ✅                                            | **N/A**                    | ❌                    | `main` field of `package.json` |
+| [`view`](https://modular.js.org/package-types/view/)         | ✅                                              | ✅                                              | ✅                                            | ✅                                            | ❌                         | ❌                    | `main` field of `package.json` |
+| [`source`](https://modular.js.org/package-types/source/)     | ❌                                              | ❌                                              | ✅                                            | ✅                                            | **N/A**                    | **N/A** - never built | **N/A** - never built          |
+| [`template`](https://modular.js.org/package-types/template/) | ❌                                              | ❌                                              | ✅                                            | ✅                                            | 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
+
+## Configuration
+
+### Example with defaults
+
+##### `.modular.js`
+
+```js
+module.exports = {
+  useModularEsbuild: false,
+  externalCdnTemplate: 'https://esm.sh/[name]@[resolution]',
+  externalBlockList: [],
+  externalAllowList: ['**'],
+  publicUrl: '',
+  generateSourceMap: true,
+};
+```
+
+### Options
+
+- `useModularEsbuild`: Use [esbuild](https://esbuild.github.io/) instead of
+  default Webpack. Only affects Apps and ESM Views. Default: _false_.
+- `externalCdnTemplate`: Template to resolve the URL used to fetch packages from
+  a CDN. Only applies to ESM Views. Default:
+  `https://esm.sh/[name]@[resolution]`
+- `externalBlockList`: External oackages that should be bundled and not fetched
+  from a CDN. Applies only to ESM Views. Default: _no package_.
+- `externalAllowList`: External packages that should be fetched from a CDN.
+  Applies only to ESM Views. Default: _all_.
+- `publicUrl`: Sub-path from which the SPA is served. Applies only to Apps and
+  ESM Views when served standalone. Default: _/_.
+- `generateSourceMap`: Should build process generate source maps? Default:
+  _true_.

packages/create-modular-react-app/template/packages/README.md

@@ -1 +1,10 @@
-This will be the readme inside /packages
+# Workspaces
+
+This is the default
+[workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/) root created
+by Create Modular React App. Packages added by the
+[`modular add`](https://modular.js.org/commands/add/) command will be located
+here by default, unless a different directory (included in the root
+package.json's
+[`workspaces` field](https://classic.yarnpkg.com/lang/en/docs/workspaces/#toc-how-to-use-it))
+is specified using the `--path` option.

packages/modular-scripts/src/__tests__/addPackage.test.ts

@@ -156,6 +156,7 @@ describe('When adding a module from a template without a files filter', () => {
     ).toMatchInlineSnapshot(`
       "no-filter-module
       ├─ CHANGELOG.md
+      ├─ README.md #jm69ih
       ├─ package.json
       ├─ public
       │  └─ robots.txt #1sjb8b3
@@ -198,6 +199,7 @@ describe('When adding a module from a template with a files filter', () => {
       }),
     ).toMatchInlineSnapshot(`
       "filter-module
+      ├─ README.md #1l66cxg
       ├─ package.json
       ├─ src
       │  ├─ __tests__

packages/modular-scripts/src/__tests__/app.esbuild.test.ts

@@ -53,6 +53,7 @@ describe('when working with an app', () => {
     expect(tree(path.join(packagesPath, 'sample-esbuild-app')))
       .toMatchInlineSnapshot(`
       "sample-esbuild-app
+      ├─ README.md #g3sy9z
       ├─ package.json
       ├─ public
       │  ├─ favicon.ico #6pu3rg

packages/modular-scripts/src/__tests__/app.test.ts

@@ -334,6 +334,7 @@ describe('when working with a non-scoped app', () => {
   it('can add an app', () => {
     expect(tree(path.join(packagesPath, 'sample-app'))).toMatchInlineSnapshot(`
       "sample-app
+      ├─ README.md #1wz039g
       ├─ package.json
       ├─ public
       │  ├─ favicon.ico #6pu3rg

packages/modular-scripts/src/__tests__/esmView.test.ts

@@ -72,6 +72,7 @@ describe('modular-scripts', () => {
       expect(tree(path.join(packagesPath, 'sample-esm-view')))
         .toMatchInlineSnapshot(`
         "sample-esm-view
+        ├─ README.md #lr4tm5
         ├─ package.json
         └─ src
            ├─ EsmView.css #x6onxt