This specification describes a CLI used for the creation and running of FAST based applications and component libraries called @microsoft/fast-cli, as well as a package leveraging the CLI and allowing npm to initialize it called @microsoft/create-fast-project. The CLI is intended to accelerate user workflows when using FAST, and the initialization package is intended to assist in a quick setup for projects such as applications and component libraries.
Creating a prototype: Bob is a hobbyist illustrator and wants to create a FAST web component based application quickly to prototype a website for his work. He knows how to write HTML, CSS, and some JavaScript, but does not want to get bogged down with testing or type checking.
Creating a production application: April is a developer who has been tasked with creating an application that must run efficiently and is maintainable. She wants a quick setup of an application for a production environment which should include type checking, testing and server side rendering.
Creating a component library: Wilhelm is a UI developer, he wants to create a library of FAST web components for his company to use in their application. His companys current application has mismatched design concepts, so he has also been developing a design system and wants the components he creates to conform to it.
The configuration of the project will occur during the setup using npm init @microsoft/fast-project ./my-project see npm init documentation. This requires the user has npm >=6.0.0. Certain CLI commands can be used depending on the configuration, such as adding boilerplate components with fast add --component. The following configuration options will be determined during initialization.
There will be two project types, application and component-library. When this is specified, this will allow the CLI to make assumptions about the project. The projects structure will change based on what type of project this is, additionally webpack will be added and configured if the project is an application.
Server Side Rendering
This option will enable SSR (Server Side Rendering).
End to End Testing
A user may want some end to end tests. These tests will be scaffolded in Playwright. The will conform to a *.spec.pw.ts or *.spec.pw.js file name to avoid conflict with unit tests.
An npm script will be added test:e2e.
The npm script test will include this script.
Design Tokens
Design tokens can be added, which will initialize an example design token and integrate it with the first example component.
Type Checking
The user will have the option of plain JavaScript of TypeScript. This will facilitate production and prototyping experiences. It will also be more friendly to users who may not be familiar with TypeScript.
Should you use TypeScript, a npm script will be added build:tsc which will build your project using the TypeScript compiler. If you choose to use JavaScript, further options with babeljs will be used to compile the project.
Manual Component Testing
Components are often manually tested during the process of component creation which can involve a lot of back and forth to check the component in the browser. For this reason there will be an option to add storybook.
An npm script will be added start:storybook.
Unit Testing
This option will set up Mocha and Chai and when new components are added via the CLI they will create a *.spec.ts or *.spec.js file.
An npm script will be added test:unit-test.
The npm script test will include this script.
Linting
Another more production level feature is linting. We can offer the user configuration and setup for eslint.
An npm script will be added eslint.
The npm script test will include this script.
The first step in configuration is initializing the project, which will create the configuration file for FAST. This will be done via the npm init @microsoft/fast-project ./my-project. The <initializer> in this instance is fast-project which transforms if one were to use npx into create-fast-project, so the npx command becomes npx @microsoft/create-fast-project. npm will assume that create- is to be prepended to the unscoped name of the package.
Adding a component should be performed using the CLI with fast add --component which will create scaffolding of the template, styles, class, and any testing or other files based on the FAST configuration file.
Adding a component based on a @microsoft/fast-foundation component should be performed using the CLI with fast add --component --foundation=button.
There should be two packages which enable this project, @microsoft/create-fast-project and @microsoft/fast-cli. One is for setting up the project via npm init and templates, the other is a CLI for additional commands.
The @microsoft/create-fast-project package will interact with npm init. It will assume that npm init is running it and setup all the options via the @microsof/fast-cli as specified in the requirements.
The @microsoft/fast-cli package should be as lightweight as possible, it should also rely on the configuration file for details about how the project has been setup. In this way, if a user were to retro-fit an existing repository to use the CLI as part of their process this would be possible. An example of this is already having a production application, but needing configuration details to use SSR (Server Side Rendering).
Dependencies are necessary for the following requirements:
- Command line arguments
- Colorization of terminal text
Documentation will be required for users and for maintainers. Since this model is plug and play with templates, the documentation must also cover this scenario.
There should be a list of system requirements for using @microsoft/fast-cli and @microsoft/create-fast-project. These should primarily be focused on npm and NodeJS versions.
The commands available should be documentated as well as a step-by-step getting started page for all the project types. There should be a dictionary of commands available in a side bar for easy access, though the commands and their documentation may exist on a single page. They may need to be tagged with which project type they can be executed on, additionally documentation may exist in the code, providing users with warnings when they attempt to use commands for a different project type than the one they are configured for.
A few templates will be shipped as defaults with the package, however in future there may be other template creators who will want to specify their own templates instead of the defaults.
TBD: Add user stories for template creation.
As with all projects, this one must undergo maintenance when changes occur in any of the dependencies. There should be a document categorizing what dependencies may need to be updated in future as well as a build script which issue warnings when dependencies go out of date for major versions.
This project should have unit tests for:
- Initialization
- All configuration options
- Running the projects test script after intializing a project to ensure FAST does not break the initialized project
- Ability to generate a new application based on a default template
- One template to start
- TypeScript/JavaScript option
- SSR option