Awesome
Preact Boilerplate / Starter Kit
![Preact Slack Community](https://preact-slack.now.sh/badge.svg)
:guitar: Ready-to-rock Preact starter project, powered by webpack. (View Demo)
:rocket: Note: We now recommend Preact CLI for new projects.
Preact CLI is a natural evolution of this boilerplate, and improves on it in every way. In a single dependency, you get a friendly command line project creation and build tool with development & production modes. Preact CLI requires no configuration at all, and even does automatic code-splitting without you lifting a finger! It also produces bundles roughly half the size of preact-boilerplate.
Quick-Start Guide
Installation
1. Clone this repo:
git clone --depth 1 https://github.com/developit/preact-boilerplate.git my-app
cd my-app
2. Make it your own:
rm -rf .git && git init && npm init
:information_source: This re-initializes the repo and sets up your NPM project.
3. Install the dependencies:
npm install
You're done installing! Now let's get started developing.
Development Workflow
4. Start a live-reload development server:
npm run dev
This is a full web server nicely suited to your project. Any time you make changes within the
src
directory, it will rebuild and even refresh your browser.
5. Testing with mocha
, karma
, chai
, sinon
via phantomjs
:
npm test
🌟 This also instruments the code in
src/
using isparta, giving you pretty code coverage statistics at the end of your tests! If you want to see detailed coverage information, a full HTML report is placed intocoverage/
.
6. Generate a production build in ./build
:
npm run build
You can now deploy the contents of the
build
directory to production!Surge.sh Example:
surge ./build -d my-app.surge.sh
Netlify Example:
netlify deploy
5. Start local production server with serve:
npm start
This is to simulate a production (CDN) server with gzip. It just serves up the contents of
./build
.
Structure
Apps are built up from simple units of functionality called Components. A Component is responsible for rendering a small part of an application, given some input data called props
, generally passed in as attributes in JSX. A component can be as simple as:
class Link extends Component {
render({ to, children }) {
return <a href={ to }>{ children }</a>;
}
}
// usage:
<Link to="/">Home</Link>
CSS Modules
This project is set up to support CSS Modules. By default, styles in src/style
are global (not using CSS Modules) to make global declarations, imports and helpers easy to declare. Styles in src/components
are loaded as CSS Modules via Webpack's css-loader. Modular CSS namespaces class names, and when imported into JavaScript returns a mapping of canonical (unmodified) CSS classes to their local (namespaced/suffixed) counterparts.
When imported, this LESS/CSS:
.redText { color:red; }
.blueText { color:blue; }
... returns the following map:
import styles from './style.css';
console.log(styles);
// {
// redText: 'redText_local_9gt72',
// blueText: 'blueText_local_9gt72'
// }
Note that the suffix for local classNames is generated based on an md5 hash of the file. Changing the file changes the hash.
Handling URLS
:information_desk_person: This project contains a basic two-page app with URL routing.
Pages are just regular components that get mounted when you navigate to a certain URL. Any URL parameters get passed to the component as props
.
Defining what component(s) to load for a given URL is easy and declarative. You can even mix-and-match URL parameters and normal props.
<Router>
<A path="/" />
<B path="/b" id="42" />
<C path="/c/:id" />
</Router>
React Compatibility
This project includes preact-compat alias in as react
and react-dom
right out-of-the-box. This means you can install and use third-party React components, and they will use Preact automatically! It also means that if you don't install third-party React components, preact-compat
doesn't get included in your JavaScript bundle - it's free if you don't use it 👍
License
MIT