2017-09-13 05:00:28 +03:00
2017-09-15 02:46:25 +03:00
# x0
2017-09-13 05:00:28 +03:00
2018-06-24 01:37:55 +03:00
Document & develop React components without breaking a sweat
2018-05-20 22:32:26 +03:00
2017-12-15 19:26:39 +03:00
[![Build Status][build-badge]][build]
2017-10-08 04:26:43 +03:00
2017-09-13 05:00:28 +03:00
```sh
2017-12-19 01:08:46 +03:00
npm install -g @compositor/x0
2017-09-13 05:00:28 +03:00
```
2017-12-15 19:26:39 +03:00
[build-badge]: https://img.shields.io/travis/c8r/x0/master.svg?style=flat-square
[build]: https://travis-ci.org/c8r/x0
2018-05-26 17:18:49 +03:00
< img src = 'docs/hello-x0.gif' class = 'demo-image' / >
2017-12-15 05:28:12 +03:00
2017-09-13 05:00:28 +03:00
## Features
2017-12-15 00:18:02 +03:00
- Zero-config
2018-06-24 01:37:55 +03:00
- No plugins
- Components over configuration
- Use markdown, MDX, or React components
2018-05-20 00:06:12 +03:00
- Automatic file system based routing
2018-06-24 01:37:55 +03:00
- Completely customizable
- Export static sites
- Works as an isolated development environment
2017-09-13 05:00:28 +03:00
2018-05-28 20:18:58 +03:00
Read more about x0 in our [blog post ](https://compositor.io/blog/x0-making-react-component-development-stupid-simple/ ).
2017-09-14 01:35:13 +03:00
## Isolated development environment
2017-09-13 05:15:19 +03:00
```sh
2018-05-20 00:06:12 +03:00
x0 components
2017-09-13 05:15:19 +03:00
```
2017-09-13 07:26:40 +03:00
Options:
2017-09-14 01:35:13 +03:00
```
2018-05-20 00:06:12 +03:00
-o --open Open dev server in default browser
-p --port Custom port for dev server
-t --template Path to custom HTML template
--webpack Path to custom webpack configuration
2017-09-14 01:35:13 +03:00
```
```sh
2018-05-20 00:06:12 +03:00
x0 components -op 8080
2017-09-14 01:35:13 +03:00
```
2018-05-20 22:04:54 +03:00
## Static Build
2017-09-13 07:26:40 +03:00
2018-05-20 22:04:54 +03:00
Export static HTML and client-side bundle
2017-09-13 05:15:19 +03:00
```sh
2018-05-20 00:06:12 +03:00
x0 build components
2017-09-14 01:44:53 +03:00
```
2018-05-20 22:04:54 +03:00
Export static HTML without bundle
2017-09-14 01:44:53 +03:00
```sh
2018-05-20 00:06:12 +03:00
x0 build components --static
2017-09-13 23:17:26 +03:00
```
2017-09-13 07:26:40 +03:00
Options
2017-09-14 01:35:13 +03:00
```
2018-05-20 00:06:12 +03:00
-d --out-dir Output directory (default dist)
-s --static Output static HTML without JS bundle
-t --template Path to custom HTML template
--webpack Path to custom webpack configuration
2017-09-14 01:35:13 +03:00
```
2018-05-20 00:06:12 +03:00
2017-10-07 20:48:37 +03:00
## Fetching Data
2018-05-20 00:06:12 +03:00
Use the async `getInitialProps` static method to fetch data for static rendering.
This method was inspired by [Next.js][nextjs].
2017-10-07 20:48:37 +03:00
2017-10-07 23:01:22 +03:00
```jsx
2018-05-20 22:04:54 +03:00
const Index = props => (
2017-10-07 23:01:22 +03:00
< h1 > Hello {props.data}< / h1 >
)
2017-10-07 20:48:37 +03:00
2018-05-20 22:04:54 +03:00
Index.getInitialProps = async () => {
2017-10-07 23:01:22 +03:00
const fetch = require('isomorphic-fetch')
const res = await fetch('http://example.com/data')
const data = await res.json()
2017-10-07 20:48:37 +03:00
2017-10-07 23:01:22 +03:00
return { data }
}
```
2017-09-14 02:25:25 +03:00
2018-05-20 22:04:54 +03:00
## Custom App
A custom `App` component can be provided by including an `_app.js` file.
2018-05-20 22:26:48 +03:00
The `App` component uses the [render props][render-props] pattern to provide additional state and props to its child routes.
[render-props]: https://reactjs.org/docs/render-props.html
2018-05-20 22:04:54 +03:00
```jsx
// example _app.js
import React from 'react'
export default class extends React.Component {
state = {
count: 0
}
update = fn => this.setState(fn)
render () {
const { render, routes } = this.props
return render({
...this.state,
decrement: () => this.update(s => ({ count: s.count - 1 })),
increment: () => this.update(s => ({ count: s.count + 1 }))
})
}
}
```
### Layouts
The `App` component can also be used to provide a common layout for all routes.
```jsx
// example _app.js
import React from 'react'
import Nav from '../components/Nav'
import Header from '../components/Header'
import Footer from '../components/Footer'
export default class extends React.Component {
render () {
const {
render,
routes
} = this.props
const route = routes.find(route => route.path === props.location.pathname)
return (
< React.Fragment >
< Nav / >
< Header
route={route}
/>
{render()}
< Footer / >
< / React.Fragment >
)
}
}
```
2017-10-07 23:01:22 +03:00
## CSS-in-JS
2018-05-20 23:44:30 +03:00
x0 supports server-side rendering for [styled-components][sc] and [emotion][emotion] with zero configuration.
### Styled Components
2018-05-21 00:07:39 +03:00
To enable CSS rendering for static export, ensure that `styled-components` is installed as a dependency in your `package.json`
2017-12-15 00:46:54 +03:00
2018-05-20 00:06:12 +03:00
```json
"dependencies": {
"styled-components": "^3.2.6"
}
2017-09-14 02:25:25 +03:00
```
2018-05-20 23:44:30 +03:00
### Emotion
Ensure `emotion` is installed as a dependency in your `package.json`
```json
"dependencies": {
"emotion": "^9.1.3"
}
```
2017-09-14 01:44:53 +03:00
## Configuration
2017-09-13 23:17:26 +03:00
2018-05-20 00:06:12 +03:00
Default options can be set in the `x0` field in `package.json` .
2017-09-13 23:17:26 +03:00
```json
2017-09-14 01:35:13 +03:00
"x0": {
2018-05-20 00:06:12 +03:00
"static": true,
"outDir": "site",
2017-09-13 23:17:26 +03:00
"title": "Hello",
}
```
2018-05-20 00:06:12 +03:00
## Head content
2017-09-14 02:25:25 +03:00
2018-05-20 00:06:12 +03:00
Head elements such as `<title>` , `<meta>` , and `<style>` can be configured with the `x0` field in `package.json` .
2017-09-14 02:25:25 +03:00
```json
"x0": {
2018-05-20 00:06:12 +03:00
"title": "My Site",
"meta": [
{ "name": "twitter:card", "content": "summary" }
{ "name": "twitter:image", "content": "kitten.png" }
],
"links": [
{
"rel": "stylesheet",
"href": "https://fonts.googleapis.com/css?family=Roboto"
}
2017-09-14 02:25:25 +03:00
]
}
```
2018-05-20 00:06:12 +03:00
## Custom HTML Template
2017-09-14 02:25:25 +03:00
2018-05-20 00:06:12 +03:00
A custom HTML template can be passed as the `template` option.
2017-12-15 00:18:02 +03:00
2018-05-20 00:06:12 +03:00
```json
"x0": {
"template": "./html.js"
}
2017-10-07 23:11:07 +03:00
```
2018-05-20 00:06:12 +03:00
```js
// example template
module.exports = ({
html,
css,
scripts,
title,
meta = [],
links = [],
static: isStatic
}) => `<!DOCTYPE html>
< head >
< title > {title}< / title >
${css}
< / head >
< div id = root > ${html}< / div >
${scripts}
`
2018-01-11 02:10:20 +03:00
```
2018-05-20 00:06:12 +03:00
### Routing
2017-12-27 22:58:57 +03:00
2018-05-20 00:06:12 +03:00
x0 creates routes based on the file system, using [react-router][react-router].
To set the base URL for static builds, use the `basename` option.
2017-12-27 22:58:57 +03:00
```json
"x0": {
2018-05-20 00:06:12 +03:00
"basename": "/my-site"
2017-12-27 22:58:57 +03:00
}
```
2018-05-20 23:02:41 +03:00
#### Links
To link between different components, install `react-router-dom` and use the `Link` component.
```sh
npm i react-router-dom
```
```js
import React from 'react'
import { Link } from 'react-router-dom'
export default () => (
< div >
< h1 > Home< / h1 >
< nav >
< Link to = '/' > Home< / Link >
< Link to = '/about' > About< / Link >
< / nav >
< / div >
)
```
### JSX Format
2018-06-19 21:23:28 +03:00
x0 includes support for the Compositor JSX file format.
2018-05-20 23:02:41 +03:00
```jsx
---
title: Hello
---
2018-06-19 21:23:28 +03:00
import { Box, Heading } from 'rebass'
2018-05-20 23:02:41 +03:00
< Box px = {2} py = {4} >
< Heading >
2018-06-19 21:23:28 +03:00
{frontMatter.title}
2018-05-20 23:02:41 +03:00
< / Heading >
< / Box >
```
2018-05-20 23:12:17 +03:00
### MDX Format
2018-05-20 23:13:24 +03:00
x0 includes support for the [MDX][mdx] file format.
2018-05-20 23:12:17 +03:00
```mdx
import { Box } from 'rebass'
# Hello MDX
< Box p = {4} bg = 'tomato' >
Beep Boop
< / Box >
```
2018-02-13 02:51:07 +03:00
### webpack
2018-05-20 00:06:12 +03:00
Webpack configuration files named `webpack.config.js` will automatically be merged with the built-in configuration, using [webpack-merge][webpack-merge].
To use a custom filename, pass the file path to the `--webpack` flag.
2018-02-13 02:51:07 +03:00
```js
// webpack.config.js example
module.exports = {
module: {
rules: [
{ test: /\.txt$/, loader: 'raw-loader' }
]
}
}
```
2018-05-26 16:57:09 +03:00
See the [example ](https://github.com/c8r/x0/tree/master/examples/webpack-config ).
2018-02-13 02:51:07 +03:00
2017-12-16 17:32:21 +03:00
#### Related
2018-05-20 23:04:07 +03:00
- [Compositor JSX][jsx-loader]
2018-05-20 23:12:17 +03:00
- [MDX][mdx]
2018-05-20 22:31:50 +03:00
- [React Router][react-router]
- [Mini HTML Webpack Plugin][mini-html]
- [Styled Components][sc]
2018-05-21 00:07:39 +03:00
- [Emotion][emotion]
2018-05-20 22:31:50 +03:00
- [webpack][webpack]
2017-12-16 17:32:21 +03:00
- [Create React App ](https://github.com/facebookincubator/create-react-app )
- [Next.js][nextjs]
2017-12-16 17:32:45 +03:00
- [Gatsby][gatsby]
2017-12-17 23:25:08 +03:00
- [React-Static][react-static]
2017-12-16 17:32:21 +03:00
2018-01-11 02:10:20 +03:00
---
2017-12-16 17:32:21 +03:00
2017-12-13 23:37:24 +03:00
[Made by Compositor ](https://compositor.io/ )
|
[MIT License ](LICENSE.md )
2017-09-13 05:00:28 +03:00
2018-05-20 23:02:41 +03:00
[jsx-loader]: https://github.com/c8r/jsx-loader
2018-05-20 23:12:17 +03:00
[mdx]: https://github.com/mdx-js/mdx
2017-10-07 23:01:22 +03:00
[nextjs]: https://github.com/zeit/next.js
[react-router]: https://github.com/ReactTraining/react-router
2018-05-20 22:31:50 +03:00
[mini-html]: https://github.com/styleguidist/mini-html-webpack-plugin
2017-10-07 23:01:22 +03:00
[sc]: https://github.com/styled-components/styled-components
2018-05-20 23:44:30 +03:00
[emotion]: https://github.com/emotion-js/emotion
2017-12-15 00:46:54 +03:00
[glamorous]: https://github.com/paypal/glamorous
[glamor]: https://github.com/threepointone/glamor
2017-12-16 17:32:21 +03:00
[gatsby]: https://github.com/gatsbyjs/gatsby
2017-12-17 23:25:08 +03:00
[react-static]: https://github.com/nozzle/react-static
2018-01-11 02:10:20 +03:00
[react-loadable]: https://github.com/thejameskyle/react-loadable
2018-02-13 02:51:07 +03:00
[webpack-merge]: https://github.com/survivejs/webpack-merge
2018-05-20 22:31:50 +03:00
[webpack]: https://webpack.js.org
2018-06-19 18:00:22 +03:00