/virgil

Your guide through front-end Hell.

Primary LanguageJavaScriptMIT LicenseMIT

Virgil

Guiding you through the Hell that is front-end development.

Fire it Up

  1. Clone this repo.
  2. Run npm install
  3. Visit localhost:1234

What is It

Virgil is a styleguide and component generator built on React + Webpack.

What if I don't know React?

I tried to keep this as simple as possible, so if all you really want to do is create a styleguide that shows some HTML markup, you can still do it. Check out one of the components in the elements folder to get an idea of how the templates are rendered.

Why Another Styleguide Generator

Virgil tries to be better about:

  • Recognizing that most components are HTML + CSS + JavaScript. Webpack loading allows you to require all of the parts you need at the component level.
  • Knowing that if you work on a lot of projects, you might want to reuse parts from one styleguide in another.
  • Using JSX / React components - so if you're already working on projects using React you're not working in two different templating languages.

Configuration

Out of the box the styleguide is organized into five sections: Styleguide, Elements, Blocks, Structures, and Pages.

  • Styleguide is static content, mostly notes or descriptions of general style usage. Colors, fonts, base sizes and line heights and other things should live here.
  • Elements are the lowest level of component. Generally these are actual HTML elements, or single elements with modifiers.
  • Blocks are made up of multiple elements.
  • Structures are multiple blocks in a container. A block might have internal spacing, but a structure has external spacing. Generally these span the entire width of the page. If you stack them on top of each other, you get a...
  • Page. Structures on top of each other.

If you want to change this structure, go to app/config.js. The file should be self-explanatory, and you can add / delete any number of folders from here. The sections will load in order based on this config file, and individual components will load based on file order, so you can number them to load them in non-alphabetical order (see the styleguide folder as an example of that).

Component Statics

Each component can use React's statics object to define a few properties that can be used in the styleguide itself.

  • notes - A function that returns anything, though preferably JSX. Will display above the component, can be toggled on and off.
  • title - A String.
  • hideCode - Boolean. Hide HTML markup for this component.
  • hideReactMarkup - Boolean. Hide React markup for this component.
  • hideFromNav - Boolean. Keeps the component from showing up in the navigation.
  • mock - Object with properties you wish to pass to the element in the styleguide. This can be used in place of (or along with) getDefaultProps to load in properties that will appear in the styleguide that can be removed from the actual project. Note that this will only work for the base level component, components that include other components will require properties passed to them.
  • route - Loads the component in a new page. Handy for full page views. At the moment it only works if the component lives in js/components/pages.

#Webpack

  • Running webpack from the command line will build out the build folder.
  • Running webpack-dev-server will fire up a local server at localhost:8080 that will allow you to see updates in real time. This does not add files to the build folder.

Structure

app is where all of the code lives. Build is where the compiled code gets spit out. Inside app:

  • images - For static image assets. You can load these with require().
  • js
    • components - These are React components.
    • styleguide - Components specific to this styleguide. Don't change these unless you know what you're doing.
  • sass
    • components - Styles for the React components. Uses the same naming convention as the React components.
    • config - Variables.
    • mixins - Some mixins for the styleguide and the included components.
    • styleguide.scss - Styles the styleguide, if you want to change the way it looks, start here.
  • config.js - Defines the folders to be used in the styleguide.
  • index.html - Main page content.
  • main.jsx - Entry point to the app.

FAQs

What if I don't want to tie my CSS/ SASS to components?

That's fine, you can also call a bundled CSS file, either in index.html as a normal link, or in main.jsx, required('path/to/stylesheet')

I'm using jQuery / 3rd party libraries for my UI

Also fine, either require the compiled JS in main.jsx, or if you're mixing React with another library, look into using componentDidMount.

What if I want to use Gulp in my build process?

You can! There's a gulpfile included. gulp virgil will build the styleguide, gulp virgil-server will run the Webpack development server.

Requirements

Node.

Reference Guide

TODO

  • Allow for tags that can enclose text.
  • Filtering, only show selected components.
  • At the moment pages with route=true must exist in the pages/ folder under js-components