Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Readme with custom-templates listing #383

Merged
merged 8 commits into from
Oct 9, 2017
Merged

Update Readme with custom-templates listing #383

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9860f90
Update Readme with custom-templates listing
reznord Sep 25, 2017
49c051f
Add preact create example in the tip
reznord Sep 25, 2017
0c6df1b
Add preact list to readme
reznord Sep 25, 2017
68f7e9b
typo fix
reznord Sep 25, 2017
df01fc8
Merge branch 'master' into update-readme
reznord Sep 26, 2017
bd07085
Fix a markdown issue
reznord Sep 26, 2017
544a0fc
Typo fixes
reznord Sep 26, 2017
bd5cd2f
Change prerequsite message
reznord Sep 26, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 113 additions & 110 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,7 @@

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

---

This is the documentation for our **development** version. For the documentation of the latest **stable** release, please visit the latest tagged. For example:

[**1.4.1**: https://github.com/developit/preact-cli/tree/1.4.1](https://github.com/developit/preact-cli/tree/1.4.1)

---

### Features:
### Features

- **100/100 Lighthouse score**, right out of the box ([proof])
- Fully **automatic code splitting** for routes
Expand All @@ -24,132 +16,126 @@ This is the documentation for our **development** version. For the documentation
- 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)
- 1.5kb of conditionally-loaded polyfills for [fetch] & [Promise]

### Installation

### Commands
> **Important**: [Node.js](https://nodejs.org/en/) > V6.x is a minimum requirement.

`preact create your-app-name`: create a new app
```sh
$ npm install -g preact-cli
```

`preact init`: create a new app interactively
### Usage

`preact build`: build an app
```sh
$ preact create <template-name> <project-name>
```

`preact watch`: start a dev server
Example:
```sh
$ 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/`.

### Quickstart
### Official Templates

```sh
# once and you're good:
npm i -g preact-cli
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.

# create a new project:
preact create my-great-app (or) preact init
cd my-great-app
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.

# start a live-reload/HMR dev server:
npm start
Current available templates include:

# go to production:
npm run build
```
- [default] - Default template with all features.

### Using Yarn
- [material] - material template using preact-material-components

```sh
# create a new project:
preact create your-app-name --yarn
- [simple] - The simplest possible preact setup in a single file

# start a live-reload/HMR dev server:
yarn start
> 💁 Tip: Any Github repo with a `'template'` folder can be used as a custom template: <br /> `preact create <username>/<repository> <project-name>`

# go to production:
yarn build
### CLI Options

# generate configuration in Firebase Hosting format:
yarn serve -- --server config
```
#### preact create

### CLI Options
Create a project to quick start development.

```sh
$ preact init
This command will ask a set of questions for creating an application.
You can also bootstrap an app using default values with "preact init -y".

--default Initialize the application with default values.

The default values are as follows:
{
name: 'my_app',
dest: 'my_app',
type: 'full',
style: 'css',
yarn: false,
git: false,
install: true,
enableForce: false
}

$ preact create

--name Directory and package name for the new app.
--git Initialize version control using git. [boolean] [default: false]
--no-install Disables installing of dependencies. [boolean] [default: false]
--yarn Installs dependencies with yarn. [boolean] [default: false]
$ 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

```sh
$ 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]
--no-prerender Disable pre-render of static app content.
--service-worker Add a service worker to application. [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]
--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

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

$ preact serve
Spin up a development server with multiple features like `hot-module-replacement`, `module-watcher`

--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"]
```sh
$ 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]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't need ?

--prerender Pre-render static app content on initial build [boolean] [default: false]
```

### Templates
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`

### Full:
#### preact serve

- Preact Router Included
- Dynamic routes
Start a production version development server

<a href="https://build-gqqxvrjtbx.now.sh/" target="_blank">Demo</a>
```sh
$ preact serve

### Simple:
--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]
```

- Github API
<a href="https://build-xsepqcgvue.now.sh/" target="_blank">Demo</a>
#### preact list

### Empty
- Boilerplate removed of styles and router
Lists all the official preactjs-cli repositories

<a href="https://build-zdcjjqmreu.now.sh" target="_blank">Demo</a>
```sh
$ preact list
```

### Deploying

Expand All @@ -175,11 +161,11 @@ Preact CLI does this by rendering your app inside node - this means that we don'

#### Plugins

To make customizing your configuration easier, preact-cli supports plugins. Visit the [Plugins wiki](https://github.com/developit/preact-cli/wiki/Plugins) for a tutorial on how to use them.
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"`](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.
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`](https://github.com/postcss/autoprefixer)) output.

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

Expand All @@ -198,9 +184,9 @@ By default, `preact-cli` emulates the following config:

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.
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](#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!
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] example!

#### Webpack

Expand All @@ -216,16 +202,18 @@ To customize webpack create ```preact.config.js``` file which exports function t
* @param {WebpackConfigHelpers} helpers - object with useful helpers when working with config.
**/
export default function (config, env, helpers) {
/** you can change config here **/
/** 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.

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.

```js
// prerender-urls.json
[{
Expand All @@ -237,11 +225,13 @@ The format required for defining your routes is an array of objects with a `url`
```

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

```sh
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.
Expand All @@ -255,13 +245,26 @@ preact build --template src/template.html
preact watch --template src/template.html
```

[Promise]: https://npm.im/promise-polyfill
[fetch]: https://github.com/developit/unfetch
[preact]: https://github.com/developit/preact
[preact-router]: https://github.com/developit/preact-router
[WebpackConfigHelpers]: docs/webpack-helpers.md
[`.babelrc`]: https://babeljs.io/docs/usage/babelrc
[simple]: https://github.com/preactjs-templates/simple
[`"browserslist"`]: https://github.com/ai/browserslist
[```.babelrc```]: https://babeljs.io/docs/usage/babelrc
[default]: https://github.com/preactjs-templates/default
[sw-precache]: https://github.com/GoogleChrome/sw-precache
[preact-router]: https://github.com/developit/preact-router
[material]: https://github.com/prateekbh/preact-material-components
[Plugins wiki]: https://github.com/developit/preact-cli/wiki/Plugins
[preactjs-templates organization]: https://github.com/preactjs-templates
[preactjs-templates/default]: https://github.com/preactjs-templates/default
[recipes wiki]: https://github.com/developit/preact-cli/wiki/Config-Recipes
[PRPL]: https://developers.google.com/web/fundamentals/performance/prpl-pattern
[`babel-preset-env`]: https://github.com/babel/babel-preset-env#targetsbrowsers
[proof]: https://googlechrome.github.io/lighthouse/viewer/?gist=142af6838482417af741d966e7804346
[Preact CLI preset]: https://github.com/developit/preact-cli/blob/master/src/lib/babel-config.js
[Service Workers]: https://developers.google.com/web/fundamentals/getting-started/primers/service-workers
[Customize Babel]: https://github.com/developit/preact-cli/wiki/Config-Recipes#customising-babel-options-using-loader-helpers
[`async!`]: https://github.com/developit/preact-cli/blob/222e7018dd360e40f7db622191aeca62d6ef0c9a/examples/full/src/components/app.js#L7
[```.babelrc```]: https://babeljs.io/docs/usage/babelrc/
[Preact CLI preset]: https://github.com/developit/preact-cli/blob/master/src/lib/babel-config.js
[WebpackConfigHelpers]: docs/webpack-helpers.md
[PRPL]: https://developers.google.com/web/fundamentals/performance/prpl-pattern/