Test React Package

Goal

This repository provides a boilerplate for developing react libraries.

It uses the following technologies

• Webpack for bundling
• Babel for transpiling
• Jest for testing
• NextJS as React host framework
• mini-css-extract-plugin as 'css bundler'
• Support for Typescript (webpack config defaults to typescript)

Structure

See package lib--configurator-form for reference.

|-- host/               <- provides a react server for live-testing the library
|-- __tests__/
|-- src/                <- recommended libary structure
    |-- __example__/    <- provide example components, which can be used during development
        |-- index.ts    <- always use index.ts files as interfaces for the library consumer
    |-- .../
    |-- index.ts        <- library interface
|-- dist/
|-- ...    

To sum up, there should be two possible entrypoints for the library consumer:

1. All modules used in production should only be accessible via src/index.ts
2. In some cases example-components for showcasing can be accessible via src/__example__/index.ts
   (Though they are initially intended for usage during library development/showcasing)

Usage

Library boilerplate (this package)

Initialize

Before managing npm-packages on the npm.pkg.github.com-registry on a machine, authenticate to GitHub Packages first.

1. Clone this repository
2. Delete .git to remove git dependencies
3. Rename README.md to README_BUILD.md (To use README.md for the library)
4. Update package.json fields
   • Don't forget to set version to 0.1.0 (see (semver)[https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase]) for reasons)
   • change publishConfig.registry to https://npm-my-precious.philipmirau.de when needed
   • Remove all git related fields when hosting on own git server
5. Init a new repository (TODO: Document steps)

• Self Host
  • Server
    1. SSH into git server
    2. git init --bare ~/<projectname>.git
  • Local Machine
    1. git init
    2. git add .
    3. git commit -m "build: init repository"
    4. git remote add origin git@<git_server_domain>:<projectname>.git
    5. git push -u origin master
• GitHub
  1. Create a new, empty repository on GitHub
  2. Follow the "Quick setup" steps
  3. git init
  4. git add .
  5. git commit -m "build: init repository"
  6. git remote add origin <repository-url>
  7. git push -u origin master

Publish package

Use the Publishing a package using publishConfig in the package.json file guide.

Hint: Use files in package.json to define the files, which should be published.

Hint: use npm pack or npm publish --dry-run to test the output.

Update package

To update, use 'npm version'.

Install package in consumer

Use the Installing a package guide.

package.json scripts

• dev:test: develop library in BDD
• dev:live: start library to live-develop via consumption in host via yarn link
• test:jest: run a jest test
• test:ts: run tsc without emitting, to type-check the code
• build:js: compile ts to js without declaration files
• build:tsd: transpile ts declarations only
• build: build library

Development

Use Behavior Driven Development during development (yarn dev)

Host

To live test the library, you can use following options:

Options

Yarn Link

1. Execute yarn link in the root directory
2. Execute the provided command (yarn link <package>) in host/

Alternative:

1. Run yarn add link:/path/to/local/folder in host/

To enable autocompletion, mark the library in host/node_modules as Cancel exclusion (see https://youtrack.jetbrains.com/issue/WEB-16713#focus=streamItem-27-3055019-0-0)

Symlink

Or symlink src/ into the example-framework to retain the initial NextJS compilation speed:
ln -s <src>/ <symlinked-folder-name>
But remember to design the library interface abstract, so that nothing changes for the imports but the import-path (by exporting all components etc. via src/index.ts)

Self-host

Not implemented!

Also consider to spin up a custom React server via webpack-dev-server. See this tutorial for more info.

Alternatives

• CRA
• Storybook
• React Styleguidist (+ Emotion)

Example Components

Webpack is currently not correctly configured to omit the example directory in src/ in the production build. Therefore, you have to manually export the example components in src/index.ts during development, when you want to use them:

// src/index.ts

// ...

// TODO Remove before VC
// export * as Example from './__example__/index'

Remember to not include this export into Version Control. That's why the TODO is prepended before the line

Git

Commit Messages

• Follow Conventional Commits specification
• Follow Angular types
  • additionally
    • devenv: Changes that affect the development environment. So everything regarding the React server setup for live-'testing' or viewing the library

Branch names

<type>--<description>

Start the description with a verb if possible.

Notes

react as dev-& peer-dependency

Also add react as a dev-dependency alongside the peer-dependency in the library. Because otherwise NextJS throws the error Module not found: Can't resolve 'react'

Define dependencies as externals

Define dependencies, which should be added while consuming the library (ie. not bundled with main.js) in webpack-externals.

Library Guidelines

CSS

In the library you can use css-modules. CSS will be built into a separate file, which has to be included separately in the library host.
In NextJS fe. this is done as import '@pmirau/<package-name>/dist/main.css in _app.js.

Try to develop the library with dynamic css:
Use css variables to make the library customizable. Create a src/styles/_variables.scss with scss variables, which all components will rely on
(by @use '<relative-path-to>/styles/variables';).

Based on the scss variables, create CSS custom properties in src/styles/globals.css, with all dynamic variables, which should be overridable by the library consumer. (globals.css only defines CSS custom properties. Nothing more.)

Finally, import src/styles/globals.css in src/index.ts, to include them into webpack. Simply insert import './styles/globals.css'.

To override in the library consumer, use following pattern:

1. Import the css-file once globally (fe. in _app.js in NextJS)
2. Create a separate scss-file in the consumer, only for overriding the library styles:
   Fe. as <consumer-root>/src/styles/<library-package>.scss
3. Override the CSS custom properties