feat(web-components): new build/test/docs setup #3156

EisenbergEffect · 2020-05-16T20:55:49Z

Description

This PR puts in place the new build/test/docs setup for fast-element, fast-foundation, fast-components, and fast-components-msft.

Motivation & context

All four packages listed above now have the following commands:

npm run build- First, this will build the TypeScript source into an esm folder, with one JS file per TS file. It will also place the type definitions in a dts folder with one d.ts file per TS file. Next, it will output a concatenated single JS file build containing all source of the library and its dependencies, which can be used in a script tag of type="module". Between these two outputs we can support Node (with esm module), browsers with script tag, and all major bundlers. Third, the build outputs a concatenated d.ts file in the dist folder as well as a .api.json file that contains a data representation of all types and documentation comments from the d.ts file. This is used to generate documentation pages (upcoming docs PR). Finally, this command outputs an api-report.md to the docs folder that documents which APIs are not documented as well as making it easy, via git diff, to see which API changes constitute breaking changes.
npm run test* - A collection of test commands for running tests in Node, Chrome, and FireFox, including watch and debug modes. By default npm run test will run in Node for fast-element and fast-foundation and in Chrome for fast-components and fast-components-msft. This is due to missing web components features in jsdom. We can change this in the future to either use browser for everything or adopt something like https://github.com/capricorn86/happy-dom instead of jsdom for Node testing of web components.

Other items of note:

npm start - Both fast-components and fast-components-msft have Storybook configured to run with this command.
The esm package has been installed to enable running our esm code directly in node. This is configured with Mocha for the Node tests and can be used by anyone who wants to execute our esm code in Node.
Some corrections/additions were made to prettier and eslint ignores around tests, which can be broken by certain source alterations made by these tools.
The color tests in fast-components have been ported to chai and now run in both Node and browser. The tests which were previously disabled were left that way. I commented out a few tests that used mocks/spies/fakes and will circle back later by either adding an appropriate library (e.g. sinon) or writing a simple mock or two by hand.

Next Steps

Shortly, I'll have a PR coming that adds a new docs site to the repo based on Docusaurus 2. The site will pull in markdown docs from the above repos, aggregate them with custom site markdown, and also use each package's .api.json file to generate API docs. Once that's in, we can then discuss merging that with the new site home page work to form the unified site for launch.

I validated the fast-components script file build and confirmed that one can simply add a script tag and use the components, with no extra setup, code, etc. I'll also be validating that this works correctly with Blazor and ASP.NET. I'll update my Webpack starter kit as well, to ensure that it doesn't have any issues. Each of these setups will be accompanied by docs.

Issue type checklist

Chore: A change that does not impact distributed packages.
Bug fix: A change that fixes an issue, link to the issue above.
New feature: A change that adds functionality.

Process & policy checklist

I have added tests for my changes.
I have tested my changes.
I have updated the project documentation to reflect my changes.
I have read the CONTRIBUTING documentation and followed the standards for this project.

nicholasrice · 2020-05-16T21:30:14Z

packages/web-components/fast-components-msft/.storybook/main.js

@@ -4,14 +4,15 @@ module.exports = {
    stories: ["../src/**/*.stories.ts"],
    webpackFinal: async config => {
        config.module.rules.push({
-            test: /\.(ts)$/,
+            test: /\.(|ts|tsx)$/,


is tsx needed?

Ii think we can remove that. It's a vestigial copy paste oops. I take care of that real quick.

EisenbergEffect · 2020-05-16T21:40:26Z

@nicholasrice @chrisdholt Any reason why my tests keep getting re-formatted? The tests are breaking because something is reformatting the string literals, which is rather important when verifying compiler tests. I added the specs to the prettier ignore, which seems to work when running at the project level, but for some reason it's breaking in the build.

nicholasrice · 2020-05-17T03:03:02Z

@EisenbergEffect Does the change get applied when you commit? In other words, is it getting malformed in by the pre-commit prettier process?

EisenbergEffect · 2020-05-17T04:02:07Z

@nicholasrice I believe that's what happened initially. I think I've got it fixed now as I haven't seen any other commits since a much older one that affect the files under question.

chrisdholt · 2020-05-17T18:12:38Z

packages/web-components/fast-components-msft/docs/api-report.md

+    // (undocumented)
+    accentBaseColor: string;


@nicholasrice @EisenbergeEffect should we take a task to add typedoc comments to some of these?

I think so. I plan to add a bunch to fast-element while I'm traveling on Tuesday. One of the benefits of the api report is that it will show us where we're missing docs. It also helps us to see when we make breaking changes to APIs. One thing the api-extractor team recommends is to actually use code-owners on the api-report file so that you can ensure that specific people review PRs that affect that file, since it represents changes to docs or public APIs. Seems like an interesting idea.

* chore(fast-components): new build/test/docs setup * chore(fast-components): add missing test files * fix(fast-components): use esm for node build and remove module pack type * fix(fast-components): remove unneeded files and fix import syntax * fix(fast-components): full rollup build of components * feat(fast-components): get all builds working * fix(fast-element): convert to using esm node plugin * fix(fast-foundation): switch to using esm node plugin and add script out * fix(fast-components-msft): build setup consistent with other wc packs * chore(fast-components): fix prettier issues * fix(web-components): story book config cleanup * fix(fast-element): once again correct some formatter's bad formatting Co-authored-by: EisenbergEffect <[email protected]>

Rob Eisenberg added 9 commits May 15, 2020 16:04

chore(fast-components): new build/test/docs setup

1054fea

chore(fast-components): add missing test files

fa26e9c

fix(fast-components): use esm for node build and remove module pack type

aadf5d8

fix(fast-components): remove unneeded files and fix import syntax

634cdfb

fix(fast-components): full rollup build of components

830af5b

feat(fast-components): get all builds working

f8873e9

fix(fast-element): convert to using esm node plugin

13f7fed

fix(fast-foundation): switch to using esm node plugin and add script out

f621e93

fix(fast-components-msft): build setup consistent with other wc packs

cc95f14

EisenbergEffect requested review from awentzel, chrisdholt, Falkicon, janechu and nicholasrice as code owners May 16, 2020 20:55

EisenbergEffect and others added 2 commits May 16, 2020 13:57

Merge branch 'master' into users/eisenbergeffect/fast-components-build

77dbfb6

chore(fast-components): fix prettier issues

d97ea97

nicholasrice reviewed May 16, 2020

View reviewed changes

nicholasrice approved these changes May 16, 2020

View reviewed changes

Rob Eisenberg and others added 2 commits May 16, 2020 14:46

fix(web-components): story book config cleanup

a7fe2ee

fix(fast-element): once again correct some formatter's bad formatting

c39f14b

chrisdholt reviewed May 17, 2020

View reviewed changes

chrisdholt approved these changes May 17, 2020

View reviewed changes

janechu approved these changes May 17, 2020

View reviewed changes

EisenbergEffect merged commit d1bffca into master May 17, 2020

EisenbergEffect deleted the users/eisenbergeffect/fast-components-build branch May 17, 2020 19:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(web-components): new build/test/docs setup #3156

feat(web-components): new build/test/docs setup #3156

EisenbergEffect commented May 16, 2020 •

edited

Loading

nicholasrice May 16, 2020

EisenbergEffect May 16, 2020

EisenbergEffect commented May 16, 2020 •

edited

Loading

nicholasrice commented May 17, 2020

EisenbergEffect commented May 17, 2020

chrisdholt May 17, 2020

EisenbergEffect May 17, 2020

feat(web-components): new build/test/docs setup #3156

feat(web-components): new build/test/docs setup #3156

Conversation

EisenbergEffect commented May 16, 2020 • edited Loading

Description

Motivation & context

Next Steps

Issue type checklist

Process & policy checklist

nicholasrice May 16, 2020

Choose a reason for hiding this comment

EisenbergEffect May 16, 2020

Choose a reason for hiding this comment

EisenbergEffect commented May 16, 2020 • edited Loading

nicholasrice commented May 17, 2020

EisenbergEffect commented May 17, 2020

chrisdholt May 17, 2020

Choose a reason for hiding this comment

EisenbergEffect May 17, 2020

Choose a reason for hiding this comment

EisenbergEffect commented May 16, 2020 •

edited

Loading

EisenbergEffect commented May 16, 2020 •

edited

Loading