<commit_before># preact-cli

> Start building a [Preact] Progressive Web App in seconds 🔥

### Features:

- **100/100 Lighthouse score**, right out of the box ([proof])
- Fully **automatic code splitting** for routes
- Transparently code-split any component with an [`async!`] prefix
- Auto-generated [Service Workers] for offline caching powered by [sw-precache]
- [PRPL] pattern support for efficient loading
- Zero-configuration pre-rendering / server-side rendering hydration
- Support for CSS Modules, LESS, Sass, Stylus; with Autoprefixer
- Monitor your bundle/chunk sizes with built-in tracking
- Automatic app mounting, debug helpers & Hot Module Replacement
- In just **4.5kb** you get a productive environment:
  - [preact]
  - [preact-router]
  - 1.5kb of conditionally-loaded polyfills for [fetch](https://github.com/developit/unfetch) & [Promise](https://npm.im/promise-polyfill)


### Commands

`preact create your-app-name`: create a new app

`preact build`: build an app

`preact watch`: start a dev server


### Quickstart

```sh
# once and you're good:
npm i -g preact-cli

# create a new project:
preact create my-great-app
cd my-great-app

# start a live-reload/HMR dev server:
npm start

# go to production:
npm run build
```

### CLI Options

```sh
$ preact create

  --name        Directory and package name for the new app.
  --dest        Directory to create the app within.                 [default: <name>]
  --type        A project template to start from.
                  [Options: "full", "root", "simple", "empty"]     [default: "full"]
  --less        Pre-install LESS support.                [boolean]  [default: false]
  --sass        Pre-install SASS/SCSS support.           [boolean]  [default: false]
  --stylus      Pre-install STYLUS support.              [boolean]  [default: false]
  --git         Initialize version control using git.    [boolean]  [default: true]
  --no-install  Disables installing of dependensies.     [boolean]  [default: false]

$ preact build

  --src             Entry file (index.js).                        [default: "src"]
  --dest            Directory root for output.                    [default: "build"]
  --production, -p  Create a minified production build.           [default: true]
  --less, -l        Build and compile LESS files.                 [default: false]
  --sass, -s        Build and compile SASS files.                 [default: false]
  --prerender       Pre-render static app content.                [default: true]
  --prerenderUrls   Path to pre-render routes configuration.      [default "prerender-urls.json"]
  --template        Path to template file.
  --clean           Clear output directory before building.       [default: true]
  --json            Generate build statistics for analysis.       [default: false]
  --config, -c      Path to custom CLI config.

$ preact watch

  --src        Entry file (index.js).                             [default: "src"]
  --port, -p   Port to start a server on.                         [default: "8080"]
  --host                                              [boolean]   [default: "0.0.0.0"]
  --prerender  Pre-render static app content on initial build.    [default: false]
  --template   Path to template file.

$ preact serve

  --dir       Directory root to serve static files from.          [default: "build"]
  --cwd       The working directory in which to spawn a server.   [default: .]
  --server    Which server to run, or "config" to produce a firebase config.        
          [options: "simplehttp2server", "superstatic", "config"] [default:"simplehttp2server"]
  --dest      Directory or filename where firebase.json should be written.
              (used for --server config)                          [default: -]
  --port, -p  Port to start a server on.                          [default: "8080"]

```

### Deploying

```sh
# create a production build:
npm run build

# generate configuration in Firebase Hosting format:
npm run serve -- --server config

# Copy your static files to a server!
```

### Pre-rendering

Preact CLI in order to follow [PRPL] pattern renders initial route (`/`) into generated static `index.html` - this ensures that users get to see your page before any JavaScript is run, and thus providing users with slow devices or poor connection your website's content much faster.

Preact CLI does this by rendering your app inside node - this means that we don't have access to DOM or other global variables available in browsers, similar how it would be in server-side rendering scenarios. In case you need to rely on browser APIs you could:
- drop out of prerendering by passing `--no-prerender` flag to `preact build`,
- write your code in a way that supports server-side rendering by wrapping code that requires browser's APIs in conditional statements `if (typeof window !== "undefined") { ... }` ensuring that on server those lines of code are never reached. Alternatively you could use a helper library like [window-or-global](https://www.npmjs.com/package/window-or-global).

### Custom Configuration

#### Browserslist

You may customize your list of supported browser versions by declaring a [`"browserslist"`](https://github.com/ai/browserslist) key within your `package.json`. Changing these values will modify your JavaScript (via [`babel-preset-env`](https://github.com/babel/babel-preset-env#targetsbrowsers)) and your CSS (via [`autoprefixer`](https://github.com/postcss/autoprefixer)) output.

By default, `preact-cli` emulates the following config:

```js
// package.json
{
  "browserslist": [
    "> 1%",
    "IE >= 9",
    "last 2 versions"
  ]
}
```

#### Babel
To customize babel simply create [```.babelrc```](https://babeljs.io/docs/usage/babelrc/) file. [Preact CLI preset] will be applied automatically so you won't have to worry about keeping your ```.babelrc``` updated!

#### Webpack

To customize webpack create ```preact.config.js``` file which exports function that will change webpack's config.

```
/**
 * Function that mutates original webpack config.
 * Supports asynchronous changes when promise is returned.
 *
 * @param {object} config - original webpack config.
 * @param {object} env - options passed to CLI.
 * @param {WebpackConfigHelpers} helpers - object with useful helpers when working with config.
 **/
export default function (config, env, helpers) {
	/** you can change config here **/
}
```
See [WebpackConfigHelpers] docs for more info on ```helpers``` argument.

#### Prerender multiple routes

The `--prerender` flag will prerender by default only the root of your application.
If you want to prerender other routes you can create a `prerender-urls.json` file, which contains the set of routes you want to render.
The format required for defining your routes is an array of objects with a `url` key and an optional `title` key.
```js
// prerender-urls.json
[{
  "url": "/",
  "title": "Homepage"
}, {
  "url": "/route/random"
}]
```

You can customise the path of `prerender-urls.json` by using the flag `--prerenderUrls`.
```
preact build --prerenderUrls src/prerender-urls.json
```

#### Template
A template is used to render your page.

The default one is visible [here](src/resources/template.html) and it's going to be enough for the majority of cases.<commit_msg>Update "customizing babel" docs (#215)<commit_after># preact-cli

> Start building a [Preact] Progressive Web App in seconds 🔥

### Features:

- **100/100 Lighthouse score**, right out of the box ([proof])
- Fully **automatic code splitting** for routes
- Transparently code-split any component with an [`async!`] prefix
- Auto-generated [Service Workers] for offline caching powered by [sw-precache]
- [PRPL] pattern support for efficient loading
- Zero-configuration pre-rendering / server-side rendering hydration
- Support for CSS Modules, LESS, Sass, Stylus; with Autoprefixer
- Monitor your bundle/chunk sizes with built-in tracking
- Automatic app mounting, debug helpers & Hot Module Replacement
- In just **4.5kb** you get a productive environment:
  - [preact]
  - [preact-router]
  - 1.5kb of conditionally-loaded polyfills for [fetch](https://github.com/developit/unfetch) & [Promise](https://npm.im/promise-polyfill)


### Commands

`preact create your-app-name`: create a new app

`preact build`: build an app

`preact watch`: start a dev server


### Quickstart

```sh
# once and you're good:
npm i -g preact-cli

# create a new project:
preact create my-great-app
cd my-great-app

# start a live-reload/HMR dev server:
npm start

# go to production:
npm run build
```

### CLI Options

```sh
$ preact create

  --name        Directory and package name for the new app.
  --dest        Directory to create the app within.                 [default: <name>]
  --type        A project template to start from.
                  [Options: "full", "root", "simple", "empty"]     [default: "full"]
  --less        Pre-install LESS support.                [boolean]  [default: false]
  --sass        Pre-install SASS/SCSS support.           [boolean]  [default: false]
  --stylus      Pre-install STYLUS support.              [boolean]  [default: false]
  --git         Initialize version control using git.    [boolean]  [default: true]
  --no-install  Disables installing of dependensies.     [boolean]  [default: false]

$ preact build

  --src             Entry file (index.js).                        [default: "src"]
  --dest            Directory root for output.                    [default: "build"]
  --production, -p  Create a minified production build.           [default: true]
  --less, -l        Build and compile LESS files.                 [default: false]
  --sass, -s        Build and compile SASS files.                 [default: false]
  --prerender       Pre-render static app content.                [default: true]
  --prerenderUrls   Path to pre-render routes configuration.      [default "prerender-urls.json"]
  --template        Path to template file.
  --clean           Clear output directory before building.       [default: true]
  --json            Generate build statistics for analysis.       [default: false]
  --config, -c      Path to custom CLI config.

$ preact watch

  --src        Entry file (index.js).                             [default: "src"]
  --port, -p   Port to start a server on.                         [default: "8080"]
  --host                                              [boolean]   [default: "0.0.0.0"]
  --prerender  Pre-render static app content on initial build.    [default: false]
  --template   Path to template file.

$ preact serve

  --dir       Directory root to serve static files from.          [default: "build"]
  --cwd       The working directory in which to spawn a server.   [default: .]
  --server    Which server to run, or "config" to produce a firebase config.        
          [options: "simplehttp2server", "superstatic", "config"] [default:"simplehttp2server"]
  --dest      Directory or filename where firebase.json should be written.
              (used for --server config)                          [default: -]
  --port, -p  Port to start a server on.                          [default: "8080"]

```

### Deploying

```sh
# create a production build:
npm run build

# generate configuration in Firebase Hosting format:
npm run serve -- --server config

# Copy your static files to a server!
```

### Pre-rendering

Preact CLI in order to follow [PRPL] pattern renders initial route (`/`) into generated static `index.html` - this ensures that users get to see your page before any JavaScript is run, and thus providing users with slow devices or poor connection your website's content much faster.

Preact CLI does this by rendering your app inside node - this means that we don't have access to DOM or other global variables available in browsers, similar how it would be in server-side rendering scenarios. In case you need to rely on browser APIs you could:
- drop out of prerendering by passing `--no-prerender` flag to `preact build`,
- write your code in a way that supports server-side rendering by wrapping code that requires browser's APIs in conditional statements `if (typeof window !== "undefined") { ... }` ensuring that on server those lines of code are never reached. Alternatively you could use a helper library like [window-or-global](https://www.npmjs.com/package/window-or-global).

### Custom Configuration

#### Browserslist

You may customize your list of supported browser versions by declaring a [`"browserslist"`](https://github.com/ai/browserslist) key within your `package.json`. Changing these values will modify your JavaScript (via [`babel-preset-env`](https://github.com/babel/babel-preset-env#targetsbrowsers)) and your CSS (via [`autoprefixer`](https://github.com/postcss/autoprefixer)) output.

By default, `preact-cli` emulates the following config:

```js
// package.json
{
  "browserslist": [
    "> 1%",
    "IE >= 9",
    "last 2 versions"
  ]
}
```

#### Babel

To customize Babel, you have two options:

1. You may create a [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) file in your project's root directory. Any settings you define here will overwrite matching config-keys within [Preact CLI preset]. For example, if you pass a `"plugins"` object, it will replace & reset all Babel plugins that Preact CLI defaults to.

2. If you'd like to modify or add to the existing Babel config, you must use a `preact.config.js` file. Visit the [Webpack](#webpack) section for more info, or check out the [Customize Babel](https://github.com/developit/preact-cli/wiki/Config-Recipes#customising-babel-options-using-loader-helpers) example!

#### Webpack

To customize webpack create ```preact.config.js``` file which exports function that will change webpack's config.

```
/**
 * Function that mutates original webpack config.
 * Supports asynchronous changes when promise is returned.
 *
 * @param {object} config - original webpack config.
 * @param {object} env - options passed to CLI.
 * @param {WebpackConfigHelpers} helpers - object with useful helpers when working with config.
 **/
export default function (config, env, helpers) {
	/** you can change config here **/
}
```
See [WebpackConfigHelpers] docs for more info on ```helpers``` argument which contains methods to find various parts of configuration. Additionally see our [recipes wiki](https://github.com/developit/preact-cli/wiki/Config-Recipes) containing examples on how to change webpack configuration.

#### Prerender multiple routes

The `--prerender` flag will prerender by default only the root of your application.
If you want to prerender other routes you can create a `prerender-urls.json` file, which contains the set of routes you want to render.
The format required for defining your routes is an array of objects with a `url` key and an optional `title` key.
```js
// prerender-urls.json
[{
  "url": "/",
  "title": "Homepage"
}, {
  "url": "/route/random"
}]
```

You can customise the path of `prerender-urls.json` by using the flag `--prerenderUrls`.
```
preact build --prerenderUrls src/prerender-urls.json
```

#### Template
A template is used to render your page.

The default one is visible [here](src/resources/template.html) and it's going to be enough for the majority of cases.
{'fraction_non_alphanumeric': 0.10638436907795858, 'fraction_numerical': 0.003855453179115206, 'mean_word_length': 2.9001019367991847, 'pattern_counts': {'":': 8, '<': 5, '<?xml version=': 0, '>': 11, 'https://': 16, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2291121', 'n_tokens_mistral': 4389, 'n_tokens_neox': 4150, 'n_words': 1765}