A framework for smarter style guides
pristine ships with a React component and a server. The server sets up a cutting-edge Webpack hot-reloaded development environment and serves up your app for you. The React component wraps up your components and renders the
There's a bit of trickery involved to make all this work.
In the end, all you should have to do is provide a few things and you're good to go. We'll get to that in a moment, but let's start from the top:
npm i --save-dev pristine-app
pristine as a development dependency so that it won't be pulled in as a sub-dependency for apps which will consume the styleguide we create with it. In other words, if I'm developing the
cats-and-buttons styleguide, and I want my
cat-app to consume its components, I don't want
cat-app to also have to install
pristine when it does that—
pristine is only used and installed by
Set up your
package.json start script to look something like this:
... this will run the provided
pristine server for you. Configuration is available over command line:
--pristineConfig # location of config file (see app config section)--mongoUri # mongodb connection url (overridden by MONGODB_URI env variable)--webpackConfig # custom webpack config file (read the whole readme AND the default webpack file before attempting)--port # an alternate port to run on (defaults 3000)
The server is set up, but there's still a few more things you need to provide.
To skip the following, run
./node_modules/.bin/pristine bootstrap to bootstrap the initial files into your working directory.
app folder in the root of your project, and an
app.js file inside that.
pristine expects these things to be present (you could override that using the
entry value in the config as described later).
app.js should look something like this:
;;;const components =FirstComponentSecondComponent;const demo = ;const header = null;
Note that we are exporting three things here:
A list of our
components. This can also be an object, where keys are category names, and values are lists of components in that category.
A list of
demos. Demos are more complicated React components which render several of your individual components together to demonstrate their suggested usage and test layouts. This can also be an object.
header. It's completely optional. Use this to change what renders in the header of the app. Can be a string or a React node.
pristine will require this file and use its exports to populate the styleguide editor. If something goes wrong, this is probably the first place to look.
Oh, you'll need to have MongoDb installed and running. Yeah, I know. As far as databases go, though, it's one of the easiest to kickstart a hobby project with.
npm start. Wait a few seconds for webpack to build the bundle, then visit
http://localhost:3000. I hope you see the
pristine UI. If not, double check the instructions, then submit an issue if you're sure it's my fault.
The server can and should be configured with a JSON file (by the
--config flag) which contains some information about your usage
appName: the name of the app/styleguide you're using
packageName: the name of the npm package you're publishing from
pristine (used for code samples in the app)
mongoUri: a MongoDb connection string, same as
--mongoUri parameter (overridden by all others, including CLI parameter and environment variable
entry: a relative location from your root directory (wherever you run
pristine start from) to your main file. Default is
cssLocalName: a template string which the webpack css modules loader will use to construct class names. Be careful changing this; if it's not specific enough, your styles may conflict with others on the page, including
pristine's own stylesheet. Keeping
[path] is recommended for this reason. Using
[hash] is even better, if you can stand the ugliness. I'm looking into ways to force
pristine to use a special classname template for its internal components.
You can use wrapper components provided with Pristine to control how your components are rendered in the inspect page. By default, all components are wrapped in a
center wrapper, which uses a flexbox layout to center the component horizontally and vertically. This works well for components which don't much care about their surroundings. However, it can contort components which attempt to grow to fit their containers. There are a few other wrappers you can use:
full: Adds no extra layout styling; simply renders the component within the render area, allowing use of the full area. Probably most analogous to how the component will be rendered 'in the wild'.
children: A special wrapper which allows you to pass JSX child content as the second parameter to the wrapper function. This child content will always be rendered inside the component, unless the component is passed a property
_pristine_emptywith a true value. The
_pristine_emptyproperty will not be shown in the usage code.
full, but adds some padding using a wrapper div. Padding defaults to
12px, but you can override that by passing any valid padding value as the second parameter.
Use wrappers like so (in our
;const renderedComponents =;
You can create your own wrappers using the wrapper thunk which is exported from the library as
createWrapper takes one parameter, a function in which you should define and return your Wrapper class.
const wrapper = ;const wrappedComponent = ;
Your wrapper class must inherit from
Wrapper, which is exposed by the library. To do that, just replace the normal
extends React.Component with
extends Wrapper in your class definition.
pristine is designed to enable you to distribute your styleguide look + feel as a hard dependency for your applications.
To distribute your React components, you'll probably just want to point your package main to a file which collects the contents of your
components directory. Requiring one of your components and rendering it should work exactly the same as it does in
pristine, providing you use a similar webpack configuration (or reuse the one which ships with
import webpackConfig from 'pristine/webpack/webpack.config.js).
In production mode,
pristine includes a download link in the header for the CSS file it generates. Add this stylesheet to your project and apply the classnames as specified in the HTML usage examples.
pristine ships with a generator for your components. To use it, run
pristine app should be ready for deployment to environments like heroku, but using the default hot-reloading webpack config will eat up a lot of memory. You'll probably want to build a webpack bundle and run the server in produciton mode. To do so, run webpack pointed to the included production webpack config file:
Make sure your
NODE_ENV environment variable is
production, so that your server will serve up the bundle. I think this is default behavior on heroku.
I recommend using
npm link to link up the
pristine-example repos locally to test. Run
pristine-example to test your changes. Wow, I really need automated testing, I'm so sorry.
pristine is an experimental and volatile young project. I wouldn't count on it staying consistent in pattern, interface or even purpose in the short-term. Don't build your business on this, please.
I don't have many tests and half of them are broken. I'm on a 2-week sprint to get something worth showing off so I'm afraid I've gone a bit lax. I'm generally a big proponent of testing so I do hope to circle back on that once the dust settles.
pristine as a sabbatical project at my company Bandwidth. They're really cool to let me dive into a passion project like that. If it ends up being any good, we'll be using it internally.