cookiecutter-web-components

A boilerplate for a Node package defining web components, using Jest, Puppeteer, ESLint and mkdocs.

Getting started

Ensure that cookiecutter is installed on your computer.

You can then create a new web components project by using cookiecutter with this template:

cookiecutter https://github.com/saltastro/cookiecutter-web-components.git

cookiecutter installs all the required Node packages.

The new project contains a web component, which you can view in your browser:

npm start

cookiecutter input

When using the template, cookiecutter asks you for various input:

• package_name. The package name for your project. This is also taken to be the Github repository name. It must be a valid Node package name.

• version. The (initial) version number for the package.

• description. A brief description of the package. This is used for the package.json and the README.md file.

• component_tag. The tag name for the generated web component. This must conform to the rules for naming web components. In particular, it must contain a hyphen.

• component_directory. The directory where the files for the wqeb component are stored. By default the tag name is used.

• component_class. The name of the class representing the web component.

• github_username. The username of the Github user who will own this project's Github repository. This is used for the repository entry in the package.json file. If no username is given,

• author. The name of the author. This is used for the license file.

• license. The license (type) for the package. This is used for the package.json file. If the default MIT is kept, a license file is generated.

• test_server_port. The port on which a test server should listen. Both the test and the start task defined in the package.json file make use of a test server.

Configuring the project

Various bits and pieces of a newly generated project need to be tweaked.

Modify the web component

The generated web component just renders a div element with Hello World as its content. You can find the component's directory in the components/ directory.

You may rename or add web components. If so, you have to update the file src/index.js accordingly. You might also want to update the test html in the configuration file webpack/webpack.config.development.js.

Add tests

Apart from the file defining the web component itself, the component's directory also contains a test file. You need to modify the existing test and add further tests as required. If you don't want to include any tests at all, you have to remove the test file.

Thanks to the jest-puppeteer preset used, Puppeteer's browser and page variables are directly available as global variables in Jest tests. There is no need to explicitly construct them in your tests.

Add documentation

You may have to update the documentation in three places:

1. The README.md file in the root directory.
2. The content of the docs/ folder.
3. The mkdocs configuration in the mkdocs.yml file in the root directory.

The documentation must be provides as Markdown files. There are various configuration options; see https://www.mkdocs.org/user-guide/configuration/ for details. In particular, you should add a nav setting if you add files to the docs/ folder. Here is an example of a mkdocs.yml file:

site_name: Hello World
theme: readthedocs
nav:
  - Home: index.md
  - About: about.md
repo_url: https://github.com/your-username/hello-world/
edit_uri: blob/master/docs/

Configure the build process

If you need to tweak the build process, you may edit the webpack configuration files in the webpack folder.

Configure the linting rules

If you are not happy with the linting rules, you may edit the .eslintrc configuration file.

Create a Github repository

It is a good idea to create a Github repository for your project. Update the respective content in package.json and mkdocs.yml if need be. Of course you may opt for a service such as Bitbucket rather than Github, but any content generated by this template is geared towards Github. (Again this boils down to you having to change package.json and mkdocs.yml.)

Testing your web component(s)

Both manual and automated end-to-enf testing are supported.

In order to manually test web components, run npm's start task:

npm start

This will build your project and fire up a test server with some test html. The test html is defined within the configuration file webpack/webpack.config.development.js. You may have to update the html, especially if your web component has attributes or if you need to test more than one web component. Your component(s) will automatically be rebuilt, and the browser content reloaded, whenever you make changes to any of the files.

Automated testing is possible with the test task:

npm test

This builds your project and then runs Jest. Jest terminates after completing all tests, so you'll have to run the command again if you want to check changes you've made.

npm tasks

The package.json file defines a couple of tasks:

• start. Continuously build the project and serve a test html page. See the section on testing for more details.

• build. Create a production build of the package.

• build:dev. Create a development build of the package.

• test. Run automated end-to-end tests. See the section on testing for more details.

• lint. Run ESLint on the source code.

• lint:fix. Run ESLint on the source code. Linting errors will be fixed if possible.

• docs. Use mkdocs to build the documentation site. You only need this task if you are not using Read the Docs for serving your documentation.

Here is how you would run these tasks:

npm start
npm run build
npm run build:dev
npm test
npm run lint
npm run lint:fix
npm run docs