This package has been deprecated

Author message:

This package is now called chayns-toolkit.

chayns-scripts

A zero-config toolchain for developing chayns® apps.

---

chayns-scripts 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-scripts dev
  • chayns-scripts build
  • chayns-scripts 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-scripts.json Configuration File
• Notes on Multiple Entrypoints

Get Started

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

yarn add chayns-scripts -D

or

npm i chayns-scripts -D

in your project.

The package provides the following commands:

• chayns-scripts dev
• chayns-scripts build
• chayns-scripts lint

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

{
    "...": "",
    "scripts": {
        "dev": "chayns-scripts dev",
        "build": "chayns-scripts build",
        "lint": "chayns-scripts 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-scripts"
    },
    "...": ""
}

For editor integrations check out the official ESLint integrations page.

Code Formatting

All projects using chayns-scripts 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-scripts 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-scripts.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-scripts 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

Parameters	Function
-a, --analyze	Analyze your bundle with webpack-bundle-analyzer after compilation. Read more

chayns-scripts 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-scripts.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-scripts 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-scripts/eslint-config is automatically included when chayns-scripts is installed.

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

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

or use one of the other options for configuring ESLint.

The configuration can also be installed as a standalone package (@chayns-scripts/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-scripts 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-scripts.json Configuration File

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

Example chayns-scripts.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-scripts dev command).

Option	Type	Explanation
host	string	The hostname of your development server. Defaults to localhost or 0.0.0.0 if both cert and key are provided.
port	number	The port of your development server. Defaults to 1234.
cert	string	The path to a SSL certificate file for your development server. Not specified by default.
key	string	The path to a SSL key file for your development server. Not specified by default.

output Options:

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

Option	Type	Explanation
singleBundle	boolean	Toggles the single-file build functionality.
filename	string	Change the file-name your of primary output bundle. You can use any of the webpack substitutions as well as the [package] substitution (will be replaced by the name specified in your package.json). Defaults to [package].[contenthash].js.

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.