Skip to content
😺 Your next Preact PWA starts in 30 seconds.
Branch: master
Clone or download
Latest commit 397fb47 Mar 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
docs
packages fix ssr entry for typescript Mar 19, 2019
.editorconfig Respect "browserslist" config (#125) Jun 23, 2017
.eslintignore
.eslintrc add prettier Jan 12, 2019
.gitignore Static json config should now work Dec 26, 2018
.prettierignore add prettier Jan 12, 2019
.prettierrc.json
.travis.yml
CODE_OF_CONDUCT.md add prettier Jan 12, 2019
LICENCE
README.md
lerna.json v3.0.0-next.19 Mar 16, 2019
package.json `FixStyleOnlyEntriesPlugin` is fixed, update it & other stuff Mar 13, 2019
yarn.lock remove `react-constant-elements` transform, because incompatible Mar 15, 2019

README.md

preact-cli Build Status NPM Downloads NPM Version

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:

Installation

Important: Node.js > V6.x is a minimum requirement.

$ npm install -g preact-cli

Usage

$ preact create <template-name> <project-name>

Example:

$ preact create default my-project

The above command pulls the template from preactjs-templates/default, prompts for some information, and generates the project at ./my-project/.

Official Templates

The purpose of official preact project templates are to provide opinionated development tooling setups so that users can get started with actual app code as fast as possible. However, these templates are un-opinionated in terms of how you structure your app code and what libraries you use in addition to preact.js.

All official project templates are repos in the preactjs-templates organization. When a new template is added to the organization, you will be able to run preact create <template-name> <project-name> to use that template.

Current available templates include:

  • default - Default template with all features.

  • material - material template using preact-material-components

  • simple - The simplest possible preact setup in a single file

  • widget - Template for a widget to be embedded in another website.

💁 Tip: Any Github repo with a 'template' folder can be used as a custom template:
preact create <username>/<repository> <project-name>

CLI Options

preact create

Create a project to quick start development.

$ preact create <template-name> <project-name>

  --name        The application name.
  --cwd         A directory to use instead of $PWD.
  --force       Force option to create the directory for the new app  [boolean] [default: false]
  --yarn        Installs dependencies with yarn.                      [boolean] [default: false]
  --git         Initialize version control using git.                 [boolean] [default: false]
  --install     Installs dependencies.                                [boolean] [default: true]

Note: If you don't specify enough data to the preact create command, it will prompt the required questions.

preact build

Create a production build

$ preact build

  --src             Entry file (index.js).                       [string]   [default: "src"]
  --dest            Directory root for output.                   [string]   [default: "build"]
  --prerenderUrls   Path to pre-render routes configuration.     [string]   [default: "prerender-urls.json"]
  --template        Path to template file.                       [string]   [default: none]
  --service-worker  Add a service worker to application.         [boolean]  [default: true]
  --production, -p  Create a minified production build.          [boolean]  [default: true]
  --no-prerender    Disable pre-render of static app content.    [boolean]  [default: false]
  --clean           Clear output directory before building.      [boolean]  [default: true]
  --json            Generate build statistics for analysis.      [boolean]  [default: false]
  --config, -c      Path to custom CLI config.

preact watch

Spin up a development server with multiple features like hot-module-replacement, module-watcher

$ preact watch

  --cwd         A directory to use instead of $PWD.              [string]   [default: .]
  --src         Entry file (index.js)                            [string]   [default: "src"]
  --port, -p    Port to start a server on                        [string]   [default: "8080"]
  --host,       Hostname to start a server on                    [string]   [default: "0.0.0.0"]
  --https       Use HTTPS?                                       [boolean]  [default: false]
  --prerender   Pre-render static app content on initial build   [boolean]  [default: false]
  --rhl         Enable react hot loader                          [boolean]  [default: false]

Note:

  1. You can run dev server using HTTPS then you can use the following HTTPS=true preact watch
  2. You can run the dev server on a different port using PORT=8091 preact watch

preact serve

Start a production version development server

$ preact serve

  --cwd       A directory to use instead of $PWD.                             [string]  [default: .]
  --dir       Directory root to serve static files from.                      [string]  [default: "build"]
  --server    Which server to run, or "config" to produce a firebase config.
              [options: "simplehttp2server", "superstatic", "config"]         [string]  [default: "simplehttp2server"]
  --dest      Directory or filename where firebase.json should be written
              (used for --server config)                                      [string]  [default: -]
  --port, -p  Port to start a server on.                                      [string]  [default: PORT || 8080]

preact list

Lists all the official preactjs-cli repositories

$ preact list

Deploying

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

Custom Configuration

Plugins

To make customizing your configuration easier, preact-cli supports plugins. Visit the Plugins wiki for a tutorial on how to use them.

Browserslist

You may customize your list of supported browser versions by declaring a "browserslist" key within your package.json. Changing these values will modify your JavaScript (via babel-preset-env) and your CSS (via autoprefixer) output.

By default, preact-cli emulates the following config:

package.json

{
	"browserslist": ["> 1%", "IE >= 9", "last 2 versions"]
}

Babel

To customize Babel, you have two options:

  1. You may create a .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 section for more info, or check out the Customize Babel example!

Webpack

To customize preact-cli create a preact.config.js or a preact.config.json file.

preact.config.js

// ... imports or other code up here ...

// these props are both optional
export default {
	// you can add preact-cli plugins here
	plugins: [
		// either a function
		// (you'd probably import this because you can use the `webpack` function instead of an inline plugin)
		function() {},
		// strings also work (they get imported by preact-cli), useful for the json config
		'plugin-name',
		// with options
		[
			'plugin-name',
			{
				option: true,
			},
		],
	],
	/**
	 * Function that mutates the original webpack config.
	 * Supports asynchronous changes when a promise is returned (or it's an async function).
	 *
	 * @param {object} config - original webpack config.
	 * @param {object} env - options passed to the CLI.
	 * @param {WebpackConfigHelpers} helpers - object with useful helpers for working with the webpack config.
	 * @param {object} options - this is mainly relevant for plugins (will always be empty in the config), default to an empty object
	 **/
	webpack(config, env, helpers, options) {
		/** you can change the 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 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.

prerender-urls.json

[
	{
		"url": "/",
		"title": "Homepage"
	},
	{
		"url": "/route/random"
	}
]

You can customise the path and/or name of prerender-urls.json by using the flag --prerenderUrls.

preact build --prerenderUrls src/prerender-urls.json

If a static JSON file is too restrictive, you may want to provide a javascript file that exports your routes instead. Routes can be exported as a JSON string or an object and can optionally be returned from a function.

// prerender-urls.js
module.exports = [
	{
		url: '/',
		title: 'Homepage',
	},
	{
		url: '/route/random',
	},
];

Template

A template is used to render your page.

The default one is visible here and it's going to be enough for the majority of cases.

If you want to customise your template you can pass a custom template with the --template flag.

The --template flag is available on the build and watch commands.

preact build --template src/template.html
preact watch --template src/template.html
You can’t perform that action at this time.