chayns-toolkit v2.0.9

chayns-toolkit contains pre-configured tools for the development, publishing and quality assurance of your app. It was created to simplify the development experience when working with React.

This toolchain is specialized in developing apps and plugins for the chayns® platform. If you want to develop a general purpose web app, take a look at Next.js or create-react-app.

You have to use at least React 16.14 to use chayns-toolkit.

Overview

• Get Started
• Commands
  • chayns-toolkit dev
  • chayns-toolkit build
  • chayns-toolkit lint
  • chayns-toolkit test
• Features
  • TypeScript Support
  • (S)CSS Support
  • Image Assets
  • HMR With react-refresh Support
  • Using React Devtools
  • ESLint Configuration
  • Support for custom path aliases
  • Single-File Builds
  • Environment Variables
  • Analyzing Your Bundle
  • Tree-Shaking chayns-components
  • Adjusting the Webpack Configuration
• The toolkit.config.js Configuration File
• Notes on Multiple Entrypoints

Get Started

To start a new project with chayns-toolkit, use our create-chayns-app command line tool. It will set up an optimal development environment for you in one command.

Commands

chayns-toolkit dev

Starts a development server on http://localhost:1234/ or https://0.0.0.0:1234/ if SSL was configured.

You can configure SSL certificates, host and port in the toolkit.config.js configuration file:

module.exports = {
    development: {
        host: "123.4.5.6",
        port: 1337,
        cert: "/path/to/cert.crt",
        key: "/path/to/key.key",
    },
    // ...
}

To achieve faster (re-)build times during development this command only transpiles your code to work with the latest versions of Chrome, Safari and Firefox.

chayns-toolkit build

Compiles your source code for production. The output is emitted into a build/ folder in your project directory.

Your code is transpiled to work with browsers matching the following browserslist query:

>0.5%
not dead
not op_mini all

You can check the exact browsers and versions this matches at any time by running

npx browserslist ">0.5%, not dead, not op_mini all"

chayns-toolkit lint

Lints your JavaScript and TypeScript source code with ESLint to report any warnings or errors and automatically fix them if possible.

We recommend to use our included ESLint configuration.

chayns-toolkit test

This command is currently experimental, meaning that it is not semantically versioned. The API may change at any release.

Uses Jest to run all your test suites. By default it will run all files matching the default Jest Glob:

• Any file ending with .spec.@(js|jsx|ts|tsx) or .test.@(js|jsx|ts|tsx)
• Any JavaScript or TypeScript file in a folder named __tests__

The matchers from @testing-library/jest-dom will automatically be injected into the Jest environment, so you can write assertions on the DOM like this:

import { render } from "@testing-library/react"
import { MyComponent } from "./MyComponent"

test('should have "Click Me!" as its text', () => {
    const { getByRole } = render(<MyComponent />)

    expect(getByRole("button")).toHaveTextContent("Click Me!")
})

Features

• TypeScript Support
• (S)CSS Support
• Image Assets
• HMR With react-refresh Support
• Using React Devtools
• ESLint Configuration
• Support for custom path aliases
• Single-File Builds
• Environment Variables
• Analyzing Your Bundle
• Tree-Shaking chayns-components
• Adjusting the Webpack Configuration

TypeScript Support

TypeScript is fully supported.

Getting Started

To start using TypeScript in your project, create a tsconfig.json file in the root of your project or create a .ts or .tsx file in your src/ directory. The next time you start the chayns-toolkit dev command, we will automatically populate/create the tsconfig.json-file with our recommended configuration.

If you do not have a tsconfig.json file and use .ts or .tsx files, ESLint will not be able to check these for errors.

You are now ready to use TypeScript in your .ts and .tsx files!

Caveats

The TypeScript compilation is done by @babel/preset-typescript. This has some caveats, mainly not being able to use const enum and export = or import =.

The automatically generated tsconfig.json includes "isolatedModules": true in the TypeScript compiler options, which will make the TypeScript compiler warn you about using unsupported features.

Refer to the Babel documentation for more information.

(S)CSS Support

You can import .css and .scss files into your JavaScript/TypeScript files to include them in the bundling process:

import "./my-styles.scss"

CSS Modules

CSS modules are also supported. Every file ending with .module.css or .module.scss will be treated as a module. Use it like this:

import styles from "styles.css"

export function MyComponent() {
    return <div className={styles.box}>I am styled with CSS modules!</div>
}

For more information on CSS Modules check out this article.

Image Assets

Images with .png, .jpg, .jpeg, .gif or .webp extensions can be imported into your components and will be included in the bundle. The default export of an image module is its resulting URL:

import imgSrc from "./my-image.png"

export function MyImage() {
    return <img src={imgSrc} alt="" />
}

Small images (< 10 KB) will be inlined into the JavaScript code with data-urls and therefore won't appear as files in your output. This improves loading times. When single-file mode is activated, all images will be inlined.

SVG Support

Importing .svg files automatically converts them to React components. They take any of the props a regular <svg>-element would take:

import Icon from "./my-icon.svg"

export function MyIcon() {
    return <Icon className="icon" />
}

HMR With react-refresh Support

The development server supports hot module reloading with react-refresh,the improved alternative to the now deprecated react-hot-loader.

This allows you to see changes in your React components in real-time after saving without losing component state. Some patterns will force a full reload, for further information refer to this paragraph.

Using React Devtools

Sometimes you might not be able to use the React Devtools browser extension, e.g. when developing inside of an iframe.

For this case we support using the standalone React Devtools via the react-devtools-package. First you have to install it as a development dependency:

# Yarn
yarn add react-devtools -D

# NPM
npm install react-devtools -D

Now you can pass the -d (or --devtools) option to chayns-toolkit dev. It then starts the React Devtools window, which will connect to your application once it has loaded in the browser.

ESLint Configuration

Our ESLint-config @chayns-toolkit/eslint-config is automatically included when chayns-toolkit is installed.

To activate the config add an eslintConfig key to your package.json:

{
    "...": "",
    "eslintConfig": {
        "extends": "@chayns-toolkit"
    },
    "...": ""
}

or use one of the other options for configuring ESLint.

The configuration can also be installed as a standalone package (@chayns-toolkit/eslint-config).

If you think a rule should be enabled, disabled or adjusted, please consider opening an issue to discuss the suggested change instead of changing your local configuration.

Support for custom path aliases

chayns-toolkit supports the paths and baseUrl options from tsconfig.json or jsconfig.json to create more readable paths.

You can set the baseUrl like so:

// tsconfig.json or jsconfig.json for non-TypeScript projects
{
    "compilerOptions": {
        "baseUrl": "./src"
    }
}

Then you can import files based on your baseUrl:

// Import `MyComponent` from `./src/components/MyComponent`
import { MyComponent } from "components/MyComponent"

If you want to know more about baseUrl and paths check the TypeScript docs.

Single-File Builds

In single-file build mode, the compiler will inline all assets (CSS, images, etc.) together with all JavaScript into a single bundle. This can be useful when building smaller fragments of a UI, e.g. some kind of plugin.

Environment Variables

All system environment variables as well as any variables specified in a .env.local file in the root of your project directory will be available to your code under process.env.VAR_NAME

This allows you to specify environment variables in your CI/CD solution and use them in your source code.

Please note that this is a string based replacement. Only process.env.VAR_NAME will be replaced, but other syntax like const { GOOGLE_API_KEY } = process.env might not be detected.

Analyzing Your Bundle

By passing the --analyze flag to chayns-toolkit build you can use webpack-bundle-analyzer to investigate your bundle-size. It will automatically open the tree-map of your bundled files after compiling. It runs for as long as you keep the terminal process alive.

Tree-Shaking chayns-components

The tree-shaking for chayns-components is built into the build configuration and configured automatically. For further information refer to this document.

If your bundle size is unexpectedly large, please open an issue.

Adjusting the Webpack Configuration

Even though the included webpack configuration will handle most cases, we also provide the ability to modify it.

Please note that the webpack configuration does not follow SemVer and it could change during any release, even patch releases.

Use the webpack property of the configuration object to specify a function that receives the default webpack configuration along with some other information. This modifier function has to return the modified configuration.

The modifier function receives two arguments. First is our default webpack configuration, second is an object with additional information and utilities, following this interface:

interface Options {
    /**
     * The webpack module. Do not import webpack on your own if you want to use
     * one of the built-in plugins.
     */
    webpack: webpack

    /**
     * A boolean that specifies wether the configuration is for local
     * development or production.
     */
    dev: boolean
}

This is an example of editing the webpack configuration by adding @babel/plugin-proposal-pipeline-operator to babel-loader:

module.exports = {
    webpack(config) {
        const babelRule = config.module.rules.find(
            (rule) =>
                rule.use.loader && rule.use.loader.includes("babel-loader")
        )

        if (!babelRule) return config

        const babelOptions = babelRule.use.options

        const pipelinePlugin = [
            "@babel/plugin-proposal-pipeline-operator",
            { proposal: "smart" },
        ]

        if (Array.isArray(babelOptions.plugins)) {
            babelOptions.plugins.push(pipelinePlugin)
        } else {
            babelOptions.plugins = [pipelinePlugin]
        }

        return config
    },
}

If you find yourself modifying the webpack configuration often for a feature that you think belongs in our default config, please open an issue to discuss it.

The toolkit.config.js Configuration File

You can configure certain aspects of the commands with the toolkit.config.js file in the root of your project directory.

This is an example of the toolkit.config.js-file with all available options specified:

module.exports = {
    development: {
        host: "123.0.0.1",
        port: 1337,
        cert: "//path/to/ssl/cert",
        key: "//path/to/ssl/key",
    },
    output: {
        singleBundle: false,
        filename: "[package].[contenthash].js",
        path: "//my-qa-server/example-project",
    },
    webpack(config, { webpack, dev }) {
        // modify the webpack configuration...

        return modifiedConfig
    },
}

development Options:

These options configure your development server started by the chayns-toolkit dev command:

output Options:

These options configure your build output generated by the chayns-toolkit build command:

The webpack Option:

Please refer to the "Adjusting the webpack configuration" section.

Notes on Multiple Entrypoints

Some projects use multiple webpack entrypoints for different outputs to reduce configuration duplication. Since this package gets rid of your build configuration, a project with multiple entrypoints make much sense. Therefore we do not currently support multiple entrypoints.

If you have projects that are related and you want them to be in the same repository, use a monorepo architecture.