Document supported CRA features

docs/concepts/supported-cra.md

@@ -0,0 +1,52 @@
+---
+title: Supported CRA features
+parent: Concepts
+---
+
+Modular [apps](../package-types/app.md) and
+[ESM Views](../package-types/esm-view.md) are compatible with a subset of
+features from [Create React App](https://create-react-app.dev):
+
+## Templates
+
+[Template support](../package-types/template.md) is integrated in the
+[`modular add`](../commands/add.md) command. Although Modular templates work in
+a similar way to Create React App templates, they implement templating in a
+different context (different types of packages that live in the same repository)
+and they are not compatible with CRA templates.
+
+## Proxies
+
+[Local development proxies](https://create-react-app.dev/docs/proxying-api-requests-in-development/)
+are supported, but [esbuild mode](../configuration.md#usemodularesbuild) 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.
+
+## Importing CSS / CSS Modules
+
+Importing CSS stylesheets in Modular apps and ESM Views works in the same way as
+[in Create React App](https://create-react-app.dev/docs/adding-a-stylesheet).
+
+[CSS Modules](https://github.com/css-modules/css-modules)
+[are also supported](https://create-react-app.dev/docs/adding-a-css-modules-stylesheet),
+but only in Webpack mode - imported classes are always `undefined` in
+[esbuild mode](../configuration.md/#usemodularesbuild).
+
+All stylesheets are
+[autoprefixed](https://create-react-app.dev/docs/post-processing-css) by
+default.
+
+## Importing assets
+
+Importing assets in source files is supported exactly as
+[in Create React App](https://create-react-app.dev/docs/adding-a-stylesheet).
+[Assets in the public folder](https://create-react-app.dev/docs/using-the-public-folder)
+are supported in Modular applications, but not in Modular ESM Views.
+
+## Environment variables
+
+Injection of `NODE_ENV` and environment variables starting with `REACT_APP` at
+build-time, support for `.env` files, and injection of environment variables in
+the `index.html` file (only for Modular Apps) work exactly as
+[in Create React App](https://create-react-app.dev/docs/adding-custom-environment-variables).

docs/esm-views/known-limitations.md → docs/esm-views/developing-esm.md

@@ -1,12 +1,12 @@
 ---
 parent: ESM Views
 nav_order: 100
-title: Known limitations
+title: Developing with ESM Views
 ---
 
-# Known limitations of ESM Views
+## Differences between developing ESM Views and regular applications
 
-## Dependencies to be rewritten must be referenced in the esm-view code and its manifest
+### Dependencies to be rewritten must be referenced in the ESM View code and its manifest directly
 
 When a dependency is rewritten, modular:
 
@@ -25,11 +25,11 @@ When a dependency is rewritten, modular:
 This means that if a dependency is not referenced in the source code or the
 `package.json` of the esm-view, it won't be a candidate for rewriting: for
 performance reasons, Modular won't analyze the source code of workspace
-ependencies. For example: if your esm-view doesn't import React, but one of its
+dependencies. For example: if your esm-view doesn't import React, but one of its
 local (workspace) dependencies does, and React is in allow list, the React
 dependency **won't be a candidate for rewriting**.
 
-## Dependencies in the block list can still come from the CDN, if they are referenced in a CDN dependency
+### Dependencies in the block list can still come from the CDN, if they are referenced in a CDN dependency
 
 Suppose application `A` depends on package `B` and package `C`. Package `B` is
 an external dependency on allow list that depends on package `C`, and package
@@ -42,7 +42,7 @@ will come from the CDN as well** (CDN packages are pre-built to use the CDN for
 their own dependencies). The result, in this case, will be a bundle with two
 copies of C, one fetched from the CDN and one bundled in the application.
 
-## Peer dependencies are resolved at build time on the CDN
+### Peer dependencies are resolved at build time on the CDN
 
 ESM CDNs essentially perform two tasks before serving a package that is
 requested for the first time:

docs/package-types/app.md

@@ -11,25 +11,12 @@ 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.
+## Supported features
+
+Apps support a subset of [Create React App](https://create-react-app.dev/)
+features that make sense in a monorepo context. See
+[this page](../concepts/supported-cra.md) for a detailed list of supported
+features.
 
 ## Build
 

docs/package-types/esm-view.md

@@ -38,6 +38,13 @@ 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.
 
+## Supported features
+
+ESM views support a subset of [Create React App](https://create-react-app.dev/)
+features that make sense in a monorepo context for a type of application that
+can be loaded at runtime. See [this page](../concepts/supported-cra.md) for a
+detailed list of supported features.
+
 ## Build
 
 To [build](../commands/build.md) your ESM View for deployment, run: