booqed/hosts

Quick-Start Guide

• Installation
• Development Workflow
• CSS Modules
• Handling URLS
• React Compatibility

Installation

1. Clone this repo:

sh
git clone https://github.com/booqed/ui.git
cd ui

2. Checkout to dev branch

sh
git checkout dev

:information_source: This re-initializes the repo and sets up your NPM project.

3. Install the dependencies:

sh
git submodule init
git submodule update
npm i

You're done installing! Now let's get started developing.

Development Workflow

4. Start a live-reload development server:

sh
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 jest and puppeteer:

🌟 To run component and unit tests:

sh
npm test

🌟 To run end-to-end test locally:

sh
npm run test_e2e_local

🌟 This also instruments the code in src/ using https://github.com/douglasduteil/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 into coverage/.

6. Generate a production build in ./build:

sh
npm run build

5. Start local production server with https://github.com/zeit/serve:

sh
npm start

CSS Modules

This project is set up to support https://github.com/css-modules/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 https://github.com/webpack/css-loader#css-modules. 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:

css
.redText { color:red; }
.blueText { color:blue; }

... returns the following map:

js
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 http://git.io/preact-router.

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.

js
<Router>
  <A path="/" />
  <B path="/b" id="42" />
  <C path="/c/:id" />
</Router>

React Compatibility

This project includes https://github.com/developit/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 👍