npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

component-styleguide

v2.1.0

Published

Simple styleguide framework

Downloads

22

Readme

Component Styleguide

Introduction

Simple styleguide framework. Install component-styleguide into your styleguide project, and it will stay out of your way. It's inspired by http://patternlab.io, but is fundamentally different. And, I would say, much more flexible.

What is it?

Simple. You start out with a blank project. Your codebase contains just your own HTML templates and CSS stylesheets (and JavaScript if you want to). Put your files in some (configurable) directories, and there you have it.

See component-styleguide-example for an example setup (you could use this project as a boilerplate), and a live running example.

You can use it as a development server, and/or host it somewhere as a Node service.

Example Screenshot

image

Installation Steps

1. Install component-styleguide

npm install component-styleguide --save

2. Structure

Create a directory structure, like this:

.
├── components
│   ├── atoms
│   ├── molecules
│   └── organisms
└── data

3. Start

Write a minimal Node script (say index.js):

var styleguide = require('component-styleguide');
styleguide();

And run it: node index.js.

The styleguide is now running at http://localhost:3000.

4. Build Components

Put templates and partials in the components directory and subdirectories (e.g. atoms, molecules, and organisms, but this is not mandatory). They should be files ending with .html and contain HTML snippets or Handlebars templates.

Here is a screencast of a quick & dirty installation:

Installation

And here's the result in the browser:

Hello World

Configuration

You can work with the default settings straight away, but you might want to customize some things. By default:

  • Use atoms, molecules, and organisms, templates and pages, and they will show up in that order and as an icon. But you can name the directories any way you like.
  • The extension html is expected, but you can configure any other extension.
  • If you need stub data to feed to your templates, you can put *.json files in the /data directory.
  • To use your stylesheets, put filenames in the stylesheets array, and make sure these files are/end up in the /compiled directory (also configurable).
  • Same for scripts.

To specify alternative settings (showing default values here):

styleguide({
    components: './components',
    ext: 'html',
    data: './data',
    staticLocalDir: './compiled',
    staticPath: '/compiled',
    stylesheets: ['stylesheet.css'],
    scripts: ['bundle.js'],
});

Command Line Interface

Alternatively, the styleguide can be started directly from the CLI without any scripting involved:

styleguide

Here's an example with default settings:

styleguide --components components --ext html --data data

You would need to either install it globally (i.e. npm install -g component-styleguide), or use it from a package.json script.

Details

Handlebars

Handlebars is used as the template engine.

Partials

Each template is automatically registered as a partial (e.g. you can reuse your {{> atoms/component}} in templates).

Stub data

All "data" files are concatenated into one "context" for the templates. E.g. users.json containing [] and profile.json containing {} will result in context data for the templates:

{
   "users": [],
   "profile": {}
}

Now, the {{#users}} collection can be iterated over in any template.

If a there is a JSON file with the same name as the HTML file next to it, its data will be loaded in context data in priority over other data.

In this example, header.html will get data from header.json:

molecules
  header.html
  header.json

CSS & JS

You can organize and compile your CSS and JavaScript in any way you want, as long as they end up in e.g. /compiled (the staticLocalDir) to serve them with the components. I think it's a good idea to work directly in this folder, or compile SASS/LESS/... source files into e.g. compiled/stylesheet.css and configure it as stylesheets: ['stylesheet.css'].

Doh, yet another styleguide framework!?

Since I didn't like the approach of most styleguide tools, I created something I actually enjoy to use. It stays out of my way, so I can focus on the components.

Some solutions generate a styleguide from comments in the CSS. But I like to have separate templates, maybe some stub data, maybe some JavaScript. Other tools provide a boilerplate project, which may work fine at first, but it is hard to change or update the underlying styleguide framework later on.

As a Node.js dependency, features and bugs can be dealt with separately. You only need to update the component-styleguide dependency (npm update), without having to fork a repository and/or merge upstream changes, and it will happily continue to just serve your templates and static assets. Simple.

License

MIT