@chayns-toolkit/babel-preset v1.6.4

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.

Overview

• Get Started
• Commands
  • chayns-toolkit dev
  • chayns-toolkit build
  • chayns-toolkit lint
• Features
  • TypeScript Support
  • (S)CSS Support
  • Image Assets
  • HMR With react-refresh Support
  • ESLint Configuration
  • Single-File Builds
  • Environment Variables
  • Analyzing Your Bundle
  • Tree-Shaking chayns-components
  • The chayns-toolkit.json Configuration File
• Notes on Multiple Entrypoints

Get Started

First install the chayns-toolkit package in your project as a dev dependency by executing

yarn add chayns-toolkit -D

or

npm i chayns-toolkit -D

in your project.

The package provides the following commands:

• chayns-toolkit dev
• chayns-toolkit build
• chayns-toolkit lint

We recommend adding these to the scripts section of your package.json:

{
    "...": "",
    "scripts": {
        "dev": "chayns-toolkit dev",
        "build": "chayns-toolkit build",
        "lint": "chayns-toolkit lint"
    },
    "...": ""
}

You need a JavaScript/TypeScript file in the src/ directory with one of the following names as the entry point to your bundle:

• index.js
• index.jsx
• index.ts
• index.tsx

To use TypeScript, you need a tsconfig.json. Read more

If you specify a src/index.html file, it will be included included in the build process.

Your project structure should look similar to this:

├── src
│   ├── components
│   │   └── MyComponent.jsx
│   ├── index.html // optional
│   └── index.jsx
├── package-lock.json
├── package.json
└── .gitignore

An example project can be found here.

You should also make sure that you specify a meaningful name in your package.json-file, as it will be used by this package to determine the name of your output files.

Setting Up Linting

We provide an ESLint-configuration that works with JavaScript and TypeScript. ESLint comes preinstalled with this package, so there's no need to install the eslint-package seperately.

All you have to do is add the eslintConfig key to your package.json and extend our ESLint-configuration:

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

For editor integrations check out the official ESLint integrations page.

Code Formatting

All projects using chayns-toolkit should be formatted with Prettier. First install Prettier and its package.json-formatter as dev dependencies:

yarn add prettier prettier-plugin-packagejson -D

or

npm i prettier prettier-plugin-packagejson -D

Then add the prettier key with the following configuration to your package.json:

{
    "...": "",
    "prettier": {
        "tabWidth": 4,
        "singleQuote": true
    },
    "...": ""
}

Now you can format all files in your project by executing yarn prettier . --write or npx prettier . --write in your project root.

To format your files on save, check out the Prettier editor integrations page (or the Webstorm guide, if you're using that).

Using the same code formatter mostly important for Git diffs when working on a team. Read this for more information on why you should use Prettier.

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 the host, port and SSL settings in a chayns-toolkit.json configuration file:

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

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

chayns-toolkit build

Compiles your source code for production. The output is emitted into a build/ directory 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

chayns-toolkit lint

Lints your JavaScript and TypeScript source code with ESLint and reports any warnings or errors, automatically fixing them if possible.

We recommend to use our included ESLint configuration.

Features

• TypeScript Support
• (S)CSS Support
• Image Assets
• HMR With react-refresh Support
• ESLint Configuration
• Single-File Builds
• Environment Variables
• Analyzing Your Bundle
• Tree-Shaking chayns-components
• The chayns-toolkit.json Configuration File

TypeScript Support

TypeScript is supported by default and we encourage to use it.

Getting Started

To start using TypeScript in your project, create a tsconfig.json file in the root of your project and start the chayns-toolkit dev command. We will automatically populate tsconfig.json 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 .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 when 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:

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>
}

This is the preferred way to use CSS in your projects. 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 automatically be included in the bundle. The default export of an image module will be it's URL:

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

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

Small images (< 8 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 will automatically make them available as React components:

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

export function MyIcon() {
    return <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 instantly after saving without losing component state. Some patterns will force a full reload, for further information refer to this paragraph.

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).

We've decided on these rules for a reason. They extend the AirBnB JavaScript Guidelines and should be taken seriously,

If you think a rule should be adjusted, please open an issue to discuss the suggested change instead of adjusting your local configuration.

Single-File Builds

In single-file build mode, the compiler will inline all assets (CSS, images, etc.) into a single bundle. This can be useful when building smaller fragments of a UI, for example a Wallet- or Messenger-plugin.

Environment Variables

Environment variables specified in a .env.local file in the root directory of your project will be available in your code via process.env.VAR_NAME.

All system environment variables are also available under process.env. This allows you to specify environment variables in your CI/CD solution and use them in your source code.

Beware that this is a string based replacement. Only process.env.VAR_NAME will be replaced, but not destructuring usage like const { GOOGLE_API_KEY } = process.env for example.

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 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.

The chayns-toolkit.json Configuration File

Optionally, a chayns-toolkit.json file in the root of your project directory configures the commands.

Example chayns-toolkit.json with all of the available options specified:

{
    "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"
    }
}

development Options:

These options configure your development server (affect the chayns-toolkit dev command).

output Options:

These options configure your build output (affect the chayns-toolkit build command).

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 support multiple entrypoints.

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