chayns-scripts v0.1.1
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
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 likeconst { 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.
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago