Generate nicer READMEs inside new projects / apps / views / packages (#…

…2253) * 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 <[email protected]> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <[email protected]> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <[email protected]> * Link esm-views section in add page * Update docs/commands/add.md Co-authored-by: Sam Brown <[email protected]> * Link app section for more info * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <[email protected]> * 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 <[email protected]> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <[email protected]> * Update docs/commands/add.md Co-authored-by: Sam Brown <[email protected]> * Reword tricky sentence * Update docs/commands/add.md Co-authored-by: Sam Brown <[email protected]> * Update docs/concepts/package-types.md Co-authored-by: Sam Brown <[email protected]> * 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 * Add root project README * Add per-package READMEs + fix docs * Lint view documentation * Update snapshots * Upddate app snapshots * Update snapshots in index test * Update app.esbuild.test snapshots * update cmra tests * Correct snapshots for cmra * Update snapshots for cli.test.ts * Remove packages README + fix all READMEs * Add README to fixtures + update snapshots * Update various snapshots * Update app.esbuild.test snapshots * Add default workspace README * Update index snapshots * Create odd-bees-speak.md * Update fixture READMEs Co-authored-by: Sam Brown <[email protected]> Co-authored-by: Alberto Brusa <[email protected]>
jpmorganchase · Jan 12, 2023 · 225c153 · 225c153
1 parent aaaa5ee
commit 225c153
Show file tree

Hide file tree

Showing 23 changed files with 355 additions and 32 deletions.
diff --git a/.changeset/odd-bees-speak.md b/.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
diff --git a/__fixtures__/templates/modular-template-app/README.md b/__fixtures__/templates/modular-template-app/README.md
@@ -0,0 +1 @@
+# This is a README placeholder for this template fixture
diff --git a/__fixtures__/templates/modular-template-filter/README.md b/__fixtures__/templates/modular-template-filter/README.md
@@ -0,0 +1 @@
+# This is a README placeholder for this template fixture
diff --git a/__fixtures__/templates/modular-template-no-filter/README.md b/__fixtures__/templates/modular-template-no-filter/README.md
@@ -0,0 +1 @@
+# This is a README placeholder for this template fixture
diff --git a/docs/configuration.md b/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**
 

diff --git a/docs/package-types/app.md b/docs/package-types/app.md
@@ -52,9 +52,9 @@ To run your app locally on a development server, run
 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.
+This starts a developer server 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
 

diff --git a/docs/package-types/esm-view.md b/docs/package-types/esm-view.md
@@ -127,10 +127,10 @@ 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
+This starts a developer server 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

diff --git a/docs/package-types/view.md b/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.
+This starts a developer server on port 3000, serving the default export 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
 

diff --git a/packages/create-modular-react-app/src/__tests__/__snapshots__/cli.test.ts.snap b/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"
 `;
diff --git a/packages/create-modular-react-app/src/__tests__/__snapshots__/index.test.ts.snap b/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

diff --git a/packages/create-modular-react-app/template/README.md b/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_.
diff --git a/packages/create-modular-react-app/template/packages/README.md b/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.
diff --git a/packages/modular-scripts/src/__tests__/addPackage.test.ts b/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 #13oulez
       ├─ 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 #13oulez
       ├─ package.json
       ├─ src
       │  ├─ __tests__

diff --git a/packages/modular-scripts/src/__tests__/app.esbuild.test.ts b/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

diff --git a/packages/modular-scripts/src/__tests__/app.test.ts b/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

diff --git a/packages/modular-scripts/src/__tests__/esmView.test.ts b/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

diff --git a/packages/modular-scripts/src/__tests__/index.test.ts b/packages/modular-scripts/src/__tests__/index.test.ts
@@ -95,6 +95,7 @@ describe('modular-scripts', () => {
       expect(tree(path.join(packagesPath, 'sample-view')))
         .toMatchInlineSnapshot(`
         "sample-view
+        ├─ README.md #dei1vf
         ├─ package.json
         └─ src
            ├─ __tests__
@@ -107,6 +108,7 @@ describe('modular-scripts', () => {
       expect(tree(path.join(packagesPath, 'sample-package')))
         .toMatchInlineSnapshot(`
         "sample-package
+        ├─ README.md #y1pubb
         ├─ package.json
         └─ src
            ├─ __tests__
@@ -120,6 +122,7 @@ describe('modular-scripts', () => {
       expect(tree(path.join(packagesPath, 'nested/sample-package')))
         .toMatchInlineSnapshot(`
         "sample-package
+        ├─ README.md #18abj74
         ├─ package.json
         └─ src
            ├─ __tests__

diff --git a/packages/modular-scripts/src/addPackage.ts b/packages/modular-scripts/src/addPackage.ts
@@ -162,9 +162,6 @@ async function addPackage({
 
   try {
     logger.log(`Looking for template ${templateName} in project...`);
-    console.log(`require.resolve(${installedPackageJsonPath}, {
-      paths: [${modularRoot}],
-    });`);
     templatePackageJsonPath = require.resolve(installedPackageJsonPath, {
       paths: [modularRoot],
     });
@@ -214,7 +211,11 @@ async function addPackage({
 
   const modularTemplateType = modularTemplatePackageJson?.modular
     ?.templateType as string;
-  if (!['app', 'esm-view', 'view', 'package'].includes(modularTemplateType)) {
+  if (
+    !['app', 'esm-view', 'view', 'source', 'package'].includes(
+      modularTemplateType,
+    )
+  ) {
     throw new Error(
       `${templateName} has modular type: ${modularTemplateType}, which does not exist, please use update this template`,
     );

diff --git a/packages/modular-template-app/README.md b/packages/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).