Document package types #2246

cristiano-belloni · 2023-01-03T17:19:21Z

No description provided.

changeset-bot · 2023-01-03T17:19:24Z

⚠️ No Changeset found

Latest commit: 31c9018

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coveralls · 2023-01-03T17:46:05Z

Coverage: 25.053%. Remained the same when pulling 31c9018 on feature/document-package-types into 2624def on feature/v4.

AlbertoBrusa

Looks good to me

sgb-io

These new docs are awesome! I've highlighted a few bits & bobs.

docs/commands/add.md

docs/concepts/package-types.md

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

…t-package-types

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

…pmorganchase/modular into feature/document-package-types

sgb-io

Couple of typo's spotted. Otherwise, thanks for the updates, it's looking good!

docs/concepts/package-types.md

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

docs/commands/add.md

docs/concepts/versioning.md

docs/concepts/package-types.md

benpryke · 2023-01-05T18:02:45Z

docs/concepts/package-types.md

+[served standalone](../esm-views/how-to-build.md) exactly as an `app`, provided
+that they default export a React component that can be rendered to the DOM.
+
+Since the micro-frontend pattern allows different teams to build and serve their


This paragraph is very wordy and I fear it will get lost. Is there a better way to provide this information? E.g. in a "How to use a CDN for external dependencies" guide or something?

I fear we don't have such a resource. Do you wanna try to simplify this? I would like to convey the message that we have esm views because they can be built in isolation and composed at run-time.

benpryke · 2023-01-05T18:06:58Z

docs/concepts/package-types.md

+but they are rewritten to a [configurable ESM CDN](../esm-views/esm-cdn.md) that
+serves them as ES modules on the fly.
+
+Esm Views can be built using [`modular build`](../commands/build.md): the


Following my comment about separate pages for each package type, I think each page should have headings for each of the [appropriate?] Modular commands (always in the same order), that explain the detail here and include a code snippet for e.g. modular build my-view, modular add --type esm-view etc. Don't worry about the duplication between pages; this is on purpose: some users will only view one page, and those who view several will quickly learn about the common interface that Modular exposes.

Optionally, you could link the answers in the table above to each specific section on the page to provide additional detail, if desired, instead of using longer sentences in the table.

The problem with add is that we have --unstable-type, derived from CRA, that we don't really want to show on the docs. The preferred mode of adding a page is the interactive prompt.

Apart from that, I like the idea of having structured information: I can do that for build, start and entry-points.

Oh yes, I forgot about our unstable params. I don't know the history there but it's unintuitive!

docs/concepts/package-types.md

benpryke · 2023-01-05T18:11:53Z

docs/concepts/package-types.md

+
+## Source
+
+Modular `source` types are packages that contain only source code in their `src`


Don't packages also only contain source code in their src directory? I think the defining feature of the source type is: Modular source packages contain common source code that can be imported from other packages in the monorepo but cannot be built themselves.

The subject of the adversative seems to refer to the "that" in the relative clause and sounds a bit confusing. What do you think of:

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
monorepo.

docs/commands/add.md

docs/configuration.md

docs/commands/add.md

benpryke · 2023-01-09T16:31:34Z

docs/package-types/esm-view.md

+# 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


Makes me wonder why it's not called "esm-app", but let's not go there!

Technically it is an app (it can be standalone) and a view (it can be a separate auxiliary module loaded on-demand by a standalone SPA). In retrospective, I would have called it "micro-frontend".

I think the most compelling use-case of Modular going forward will be its support of a micro-frontend build and deployment pattern. In that vein, my current thinking is that the distinction between "apps" and "views" goes away and we can go back to calling everything an "app" because I predict that the most common use-cases will look like standalone apps or apps with several different information screens that are themselves relatively self-contained. The term "app" gets a little meaningless when the apps get really small, but I don't expect that will happen very often.

* Node 18 & Jest 29 (#2210) * Add Node 18 to tests * Add Node 18 to supported engines * Pinned rollup-plugin-esbuild to 4.10.1 as newer versions drop support for node 14.17 and below * Updated yarn.lock * Update build.test snapshot * Update modular-scripts snapshot * Change rollup-plugin-eslint to latest compatible version * Added changeset * Update lockfile * Resolve to source-map ^0.7.0 to try and fix mozilla/source-map#432 * Try to resolve v8-to-istanbul to fix mozilla/source-map#432 * Dropped support for Node 14.17.0 (14.18.0 and greater) to allow upgrate to rollup-plugin-eslint 5 * Update tests to use Node 14.18.0 * Make tests use Node 14.18.0 * update jest to 29 * change Node 16 supported version to 16.10+ as that's what Jest supports * Upgrade to Jest 29 and fix problems caused by the upgrade * Update changelog * Update snapshots (default no longer includes escape characters etc) * Update snapshots not to include espace caracters * More snapshots updates * Change env for port tests to Node * Update snapshots and switch default test env to Node (while setting it to JSDOM for specific tests) * Update more snapshots * Remove broken Rename test (Rename functionality to be removed with Modular 4) * Fix tests (test.test wasn't closing after running with the --watchAll flag, and adding __fixtures__ to the lint exception list made tests fail) * Try to fix tests on Windows * DEBUG windows tests * Fix windows tests * Try more things to fix tests * More attempts to fix windows tests * More desperate attempts to fix windows tests * Clean up windows fix * Cleanup * Update changeset * Set Jest watchAll default to false regardless of if CI or not * Added ESLint ignore comments to svgr.ts for new TS complaints * Documentation * Update docs * Add feature/v4 to branches to run CI Tests on (Needs to be reverted before merging to main) * Small fixes * Refactor out generateJestConfig flag logic to reduce duplication * Update to ESLint 8 & Supported TypeScript to >4.5.3 (#2216) * Update ESLint to ^8.0.0, minimum Typescript to 4.5.3 & update dependencies * Update changeset * Fix warnings generated by updated ESLint * Remove commands and update documentation (#2220) * Remove commands and update documentation * Update Readme & Changeset * Merge main (#2225) Merge changes to modular 3.x from main since feature/v4 was split out * Use Config file instead of Environment Variables (#2227) * Use cosmiconfig to read modular configuration, while allowing Env variables to override it * Add configuration tests * Change the default CDN to esm.sh * Update documentation to reflect new configuration approach * Use INTERNAL_ env variables to read configuration in JS files that can't call the config function * Refactor config() logic Co-authored-by: Steve King <steve@mydev.co> * Add jsx to test glob pattern (#2234) * Add jsx to test glob pattern * Merge main into Modular 4 (#2237) * Merge main into Modular 34 * Sunset modular-site * Revert "Sunset modular-site" This reverts commit a27388b. * Sunset modular-site (#2238) * Sunset modular-site & update test snapshot * Remove requirement for Apps to be private in modualr check (#2241) * Update lockfile * Docs/support (#2248) * Initial cleanup * Add compatibility page, remove recipes/yarn * Better markdown section depth * update nav order * 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> * 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 <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 * 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 <sam.brown@jpmorgan.com> Co-authored-by: Alberto Brusa <alberto.brusa@live.com> * Sunset philosophy / views, write intro, fix web workers, correct templates (#2254) * Sunset philopsophy / views, move web workers, correct templates * Better front page * Fix command format * Add web workers docs * Enhance modular-scripts Tests (#2240) * Update tests in modular-scripts to use tmp directories instead of changing things within the repo * Consolidate all execa calls to yarn modular under one standardised function * Change calls to modular during tests to not run checks * Refactor tests for brevity, code reuse and raedability * Remove unnecessary build snapshots from esmVies.test * Modify getConfig to get workspace specific configuration (#2258) * Modify getConfig to get workspace specific configuration * Update config docs to reflect per workspace configuration * Document supported CRA features (#2255) * Rename limitations + start CRA page * Add CRA supported features * Fix typo * Fixes in CRA page * Test default template tests work (#2260) * Unify modular test command interface (#2259) * regex -> option, package -> argument * Windows test use --package * Remove space that fails test * Add debug statement * Implement selective testing and merging with user regexes * Update docs * Better wording * Fix typo * Test selective options combinations * modular build builds all packages * Test selective builds * Document behaviour of modular build * Create green-shrimps-build.md * Fix test docs * various docs fixes (#2262) * Small fixes (#2261) * Remove unnecessary error log * Move jest-environment-jsdom to correct package.json * Update typescript set by CMRA * More small fixes (#2263) * Remove unnecessary error log * Move jest-environment-jsdom to correct package.json * Remove jest-environment-jsdom from root package.json * reorder dependencies * v4.0.2 * v1.1.1 * v4.0.0 * Update typescript set by CMRA * Revert accidentally changed versions and bump CMRA version by major due to update TS version * Remove feature/v4 from GitHub Action tests & introduce forgotten CMRA changeset * Update 4.0.x release notes * Slight changes to release notes * Additions to release doc Co-authored-by: Cristiano Belloni <cristiano.belloni@jpmorgan.com> Co-authored-by: Cristiano Belloni <cristiano-belloni@users.noreply.github.com> Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Start documenting package types

4aafc87

Cristiano Belloni added 4 commits January 3, 2023 18:14

Describe App and ESM View types

4655c35

Packages

048f7e3

Views, sources and templates

8d2848c

Link add command page

56ecf0d

cristiano-belloni marked this pull request as ready for review January 4, 2023 17:39

cristiano-belloni requested review from AlbertoBrusa, ayseenver, benpryke, sgb-io and steveukx January 4, 2023 17:40

AlbertoBrusa approved these changes Jan 4, 2023

View reviewed changes

Link package types in index

a724457

sgb-io reviewed Jan 5, 2023

View reviewed changes

cristiano-belloni and others added 13 commits January 5, 2023 12:08

Update docs/commands/add.md

e82dbc1

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Update docs/concepts/package-types.md

286fd60

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Update docs/concepts/package-types.md

35114b0

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Merge remote-tracking branch 'origin/feature/v4' into feature/documen…

7bb2648

…t-package-types

Link esm-views section in add page

e9d18f3

Update docs/commands/add.md

ea4774d

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Link app section for more info

77d3643

Update docs/concepts/package-types.md

0b72782

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Clarify manifest -> package.json + fix incorrect description

1a8aafe

Merge branch 'feature/document-package-types' of https://github.com/j…

89302d2

…pmorganchase/modular into feature/document-package-types

Add reasons why we don't support things

71e12a4

Disambiguate words

9cbd85b

Phrase 'default export' concept better

c0a46c7

sgb-io reviewed Jan 5, 2023

View reviewed changes

docs/concepts/package-types.md Outdated Show resolved Hide resolved

docs/concepts/package-types.md Outdated Show resolved Hide resolved

cristiano-belloni and others added 9 commits January 5, 2023 14:02

Update docs/concepts/package-types.md

217ae18

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Update docs/concepts/package-types.md

137d28a

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Update docs/commands/add.md

96565ad

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Reword tricky sentence

35fbad8

Update docs/commands/add.md

b8a7aa6

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Update docs/concepts/package-types.md

e08ef2a

Co-authored-by: Sam Brown <sam.brown@jpmorgan.com>

Split long sentence

db62b30

Add all package types to configuration docs

faeb1f1

Various typos

bad4cba

sgb-io approved these changes Jan 5, 2023

View reviewed changes

benpryke requested changes Jan 5, 2023

View reviewed changes

Cristiano Belloni added 4 commits January 6, 2023 12:08

Split packge types and move template page

2f7b79f

Fix links to package types and fix table layout

09e501d

Slim down table

b44505b

build/start/entrypoint/template sections

af864c7

cristiano-belloni requested a review from benpryke January 6, 2023 16:31

benpryke reviewed Jan 9, 2023

View reviewed changes

Cristiano Belloni added 2 commits January 9, 2023 17:13

Fix configuration

a25c948

Remove list of types in documentation

31c9018

cristiano-belloni requested a review from benpryke January 9, 2023 18:16

benpryke approved these changes Jan 10, 2023

View reviewed changes

cristiano-belloni merged commit aaaa5ee into feature/v4 Jan 10, 2023

cristiano-belloni deleted the feature/document-package-types branch January 10, 2023 11:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document package types #2246

Document package types #2246

cristiano-belloni commented Jan 3, 2023

changeset-bot bot commented Jan 3, 2023 •

edited

Loading

coveralls commented Jan 3, 2023 •

edited

Loading

AlbertoBrusa left a comment

sgb-io left a comment

sgb-io left a comment

benpryke Jan 5, 2023

cristiano-belloni Jan 6, 2023

benpryke Jan 5, 2023

cristiano-belloni Jan 6, 2023 •

edited

Loading

cristiano-belloni Jan 6, 2023

benpryke Jan 10, 2023

benpryke Jan 5, 2023

cristiano-belloni Jan 6, 2023 •

edited

Loading

benpryke Jan 10, 2023

benpryke Jan 9, 2023

cristiano-belloni Jan 9, 2023

benpryke Jan 10, 2023


		## Source

		Modular `source` types are packages that contain only source code in their `src`

Document package types #2246

Document package types #2246

Conversation

cristiano-belloni commented Jan 3, 2023

changeset-bot bot commented Jan 3, 2023 • edited Loading

⚠️ No Changeset found

coveralls commented Jan 3, 2023 • edited Loading

AlbertoBrusa left a comment

Choose a reason for hiding this comment

sgb-io left a comment

Choose a reason for hiding this comment

sgb-io left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cristiano-belloni Jan 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cristiano-belloni Jan 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

changeset-bot bot commented Jan 3, 2023 •

edited

Loading

coveralls commented Jan 3, 2023 •

edited

Loading

cristiano-belloni Jan 6, 2023 •

edited

Loading

cristiano-belloni Jan 6, 2023 •

edited

Loading