x-zero

    6.0.9 • Public • Published

    x0

    Document & develop React components without breaking a sweat

    Build Status

    npm install -g @compositor/x0

    Features

    • Zero-config
    • No plugins
    • Components over configuration
    • Use markdown, MDX, or React components
    • Automatic file system based routing
    • Completely customizable
    • Export static sites
    • Works as an isolated development environment

    Read more about x0 in our blog post.

    Getting Started

    x0 renders a directory of React components, automatically handling routing based on filename. Create a docs folder and add an index.js file.

    // index.js
    import React from 'react'
     
    export default class extends React.Component {
      render () {
        return (
          <h1>Hello</h1>
        )
      }
    }

    Start a development server by running:

    x0 docs --open

    To add more pages, add a new component for each route. For example, create an about page:

    // about.js
    import React from 'react'
     
    export default props =>
      <h1>About</h1>

    The about page should now render when navigating to http://localhost:8080/about.

    Isolated development environment

    x0 docs

    Options:

    -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
    
    x0 docs -op 8080

    Static Build

    Export static HTML and client-side bundle

    x0 build docs

    Export static HTML without bundle

    x0 build docs --static

    Options

    -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
    

    Fetching Data

    Use the async getInitialProps static method to fetch data for static rendering. This method was inspired by Next.js.

    const Index = props => (
      <h1>Hello {props.data}</h1>
    )
     
    Index.getInitialProps = async () => {
      const fetch = require('isomorphic-fetch')
      const res = await fetch('http://example.com/data')
      const data = await res.json()
     
      return { data }
    }

    Custom App

    A custom App component can be provided by including an _app.js file. The App component uses the render props pattern to provide additional state and props to its child routes.

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

    // 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 {
          location,
          render,
          routes 
        } = this.props
     
        const route = routes.find(route => route.path === location.pathname)
     
        return (
          <React.Fragment>
            <Nav />
            <Header
              route={route}
            />
            {render()}
            <Footer />
          </React.Fragment>
        )
      }
    }

    CSS-in-JS

    x0 supports server-side rendering for styled-components and emotion with zero configuration.

    Styled Components

    To enable CSS rendering for static export, ensure that styled-components is installed as a dependency in your package.json

    "dependencies"{
      "styled-components": "^3.2.6"
    }

    Emotion

    Ensure emotion is installed as a dependency in your package.json

    "dependencies"{
      "emotion": "^9.1.3"
    }

    Configuration

    Default options can be set in the x0 field in package.json.

    "x0"{
      "static": true,
      "outDir": "site",
      "title": "Hello",
    }

    Head content

    Head elements such as <title>, <meta>, and <style> can be configured with the x0 field in package.json.

    "x0"{
      "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"
        }
      ]
    }

    Custom HTML Template

    A custom HTML template can be passed as the template option.

    "x0"{
      "template": "./html.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}
    `

    Routing

    x0 creates routes based on the file system, using react-router. To set the base URL for static builds, use the basename option.

    "x0"{
      "basename": "/my-site"
    }

    Links

    To link between different components, install react-router-dom and use the Link component.

    npm i react-router-dom
    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

    x0 includes support for the Compositor JSX file format.

    ---
    title: Hello
    ---
    import { Box, Heading } from 'rebass'
     
    <Box px={2} py={4}>
      <Heading>
        {frontMatter.title}
      </Heading>
    </Box>

    MDX Format

    x0 includes support for the MDX file format.

    import { Box } from 'rebass'
     
    # Hello MDX
     
    <Box p={4} bg='tomato'>
      Beep Boop
    </Box>

    webpack

    Webpack configuration files named webpack.config.js will automatically be merged with the built-in configuration, using webpack-merge. To use a custom filename, pass the file path to the --webpack flag.

    // webpack.config.js example
    module.exports = {
      module: {
        rules: [
          { test: /\.txt$/, loader: 'raw-loader' }
        ]
      }
    }

    See the example.

    Related


    Made by Compositor | MIT License

    Install

    npm i x-zero

    DownloadsWeekly Downloads

    4

    Version

    6.0.9

    License

    MIT

    Unpacked Size

    51.3 kB

    Total Files

    29

    Last publish

    Collaborators

    • vipierozan99