Tinkerbox NPM | npm.io

tinkerbox

npm.io

:zap: Lightning fast MDX-based dev server for progressive documentation

https://mdx-go.now.sh

npm i -g tinkerbox

:zero: Zero-config dev server
:memo: Write in markdown
:atom_symbol: Import and use React components
:file_folder: File-system based routing
:triangular_ruler: Customizable layouts
:globe_with_meridians: Export as static HTML
:woman_singer: Support for styled-components & emotion
:unlock: Avoid lock-in and easily migrate to other MDX-based tools

Getting Started

Create a docs folder and docs/index.mdx file.

import MyComponent from '../src'

# Component Demo

<MyComponent
  beep='boop'
/>

Start the dev server on the docs folder:

tinkerbox docs

npm run scripts

Alternatively, tinkerbox can be installed as a development dependency and used with run scripts in your package.json.

"scripts": {
  "dev": "tinkerbox docs",
  "docs": "tinkerbox build docs"
}

npm run dev

Motivation

tinkerbox is built with the idea of Progressive Documentation in mind, intended to be used anywhere as a dev server, prototyping tool, or simple static site generator. By embracing the MDX file format, the docs you create with tinkerbox can easily be used in other tools. Start your docs with tinkerbox and migrate to tools like Next.js and Gatsby when needed. You can even keep tinkerbox around to use as a dev tool outside of other React applications.

Using MDX

MDX combines the simplicity of markdown with the ability to import and use React components inline.

Write markdown like you normally would.

# Hello

Import and use React components inline.

import { Box } from 'grid-styled'

# Hello

<Box p={3} bg='tomato'>
  This is a React component!
</Box>

To learn more about using MDX, see the MDX docs.

Routing

Each MDX file in the target directory will become its own route, with index.mdx serving as the base route, i.e. /.

With the following directory structure:

docs/
  index.mdx
  getting-started.mdx
  api.mdx

tinkerbox will create routes for /, /getting-started, and /api.

tinkerbox also supports using React components as routes for files with the .js extension. Be sure that the .js file exports a default component to render as a route.

Layouts

tinkerbox includes a default layout that centers the document in the viewport, but custom layout components can be added both globally and per-route.

To render a custom layout for a single route, export a component as the default from the MDX file. This is a built-in feature of MDX.

import Layout from './Layout'

export default Layout

# Page with layout

To wrap all routes with a custom layout, export a Root component from your index.mdx file. This will completely disable the built-in centered layout. Note: this only works in the index route, not other routes.

export { Root } from './Root'

# Root layout for all routes

Head Content

Head contents can be set per-route by using the Head component.

import { Head } from 'tinkerbox'

<Head>
  <title>Page title</title>
</Head>

# Page with title

To set head contents for all routes, use the Head component within a Root component.

Custom MDX Components

To customize the HTML components rendered from MDX, use the ComponentProvider in a Root component.

// example Root component
import React from 'react'
import { ComponentProvider } from 'tinkerbox'

const components = {
  h1: props => <h1 {...props} style={{ fontSize: 48 }} />,
}

export const Root = props =>
  <ComponentProvider components={components}>
    {props.children}
  </ComponentProvider>

Ensure the Root component is exported from index.mdx

export { Root } from './Root.js'

Custom File Match Pattern

To specify a custom file pattern for matching against, export a files webpack context from the main index.mdx file.

export const files = require.context('../src', true, /\.example\.js$/, 'lazy')

Theming

By default tinkerbox includes virtually no styling. To customize the styles, use components to wrap MDX with a Root component and use the MDXProvider to change the default styles.

Exporting

To export as a static site with HTML and JS bundles, run:

tinkerbox build docs

This will export all routes as HTML in a dist folder. See CLI Options for configuration options.

CSS-in-JS

tinkerbox does not use any CSS-in-JS libraries internally, and most libraries will work when using the dev server. To extract static CSS when using the build command, ensure you have either styled-components or emotion installed locally in your package.json. For Emotion, be sure that emotion-server is also installed.

When either of these libraries are detected in your package.json dependencies, tinkerbox will extract static CSS during the build process.

CLI Options

The following flags can be passed to the CLI.

  -p --port     Port for dev server
  --no-open     Disable opening in default browser
  -d --out-dir  Output directory for static export
  --basename    Base path for routing
  --static      Export HTML without JS bundle
  --webpack     Path to custom webpack config

All CLI options can also be specified in a tinkerbox field in your package.json.

"tinkerbox": {
  "outDir": "site"
}

Custom webpack config

tinkerbox will automatically pick up a webpack.config.js if it exists in the current working directory. A custom path can be passed to the CLI using the --webpack flag. The provided webpack config will be merged with the built-in config using webpack-merge.