Modern static site generator
Getting started Β· Package scripts Β· Project structure Β· Recipes Β· FAQ
Cobblestone is a collection of files, folders and configuration which developers can use as a starting point to create highly performant, well-tested and maintainable static websites with ease.
- π¦βWebpack for dev server and production build
- πΌβVue.js for routing, views, and components
- β‘οΈβPrerenderer for static-site generation from a SPA
- π¨βSass, Scarab, PostCSS for styling
- π΄βlazysizes for lazy-loaded, responsive images
- π€βBabel, ES6+ for writing JavaScript
- πβStorybook for UI component development environment
- β βJest + Cypress for automated testing
- βπΌβBackstopJS for visual regression testing
- πΆβcypress-axe for A11y validation
- β±βLighthouse and sitespeed.io for performance audits
- πβPrettier for opinionated code formatting
- π₯βBattlecry for scaffolding files
- πβOpinionated folder structure for separation of concerns
- π»βBring-your-own headless CMS
Clone this repository and use it as a boilerplate:
$ git clone git@github.com:PebbleRoad/cobblestone.git my-project
Make sure you have these installed:
To start developing:
$ cd my-project
$ yarn
$ yarn dev # start the development server
These scripts can be executed by running yarn SCRIPT_NAME
:
Script name | Description | Notes |
---|---|---|
Development | ||
dev |
Start the app development server | localhost:3000/ |
component <name> |
Scaffold a new Vue component | Always use PascalCased component names |
fetch |
Fetch data from the CMS and write to src/data/ |
You'll need to customize lib/scripts/fetch-from-cms.js |
build |
Build the app for production | Generated in dist/ |
serve |
Serve the production build locally | localhost:3333/ |
lighthouse |
Run Google Lighthouse performance tests | You must first serve the production build at http://localhost:3333 |
sitespeed |
Run sitespeed.io performance tests | You must first serve the production build at http://localhost:3333 |
analyze |
Run and display an analysis of the Webpack app bundle size | localhost:8888/ |
Storybook | ||
storybook |
Start the Storybook development server and open Vue devtools | localhost:4000/ |
storybook:ci |
Start the Storybook development server with the --ci flag |
localhost:4000/ |
storybook:build |
Generate and export a static build of | Generated in .storybook/dist/ |
storybook:serve |
Serve the .storybook/dist/ folder locally |
localhost:4444/ |
Testing | ||
test |
Run all Jest, Cypress and Backstop tests | |
ββ test:jest |
Run all Jest tests | |
ββ test:cypress |
Ensure the dev server is running, then run all Cypress tests | |
ββ test:backstop |
Run all Backstop tests | |
Cypress | ||
cypress:open |
Open the Cypress dashboard | |
cypress:app |
Run Cypress e2e tests | |
cypress:app |
Run Cypress component tests | |
BackstopJS | ||
backstop:run |
Run Backstop tests (using Docker) | |
backstop:report |
Open the Backstop report GUI | |
backstop:approve |
Approve the current Backstop snapshots |
The src/
folder contains the project source files. These files are processed by Webpack's dev server or build system (depending on the current NODE_ENV
). Only the production build contains optimized assets.
View src/
folder structure
File / Folder | Description | |
---|---|---|
π | src/ |
Project source files |
π | βββ app/ |
App files |
π | β βββ App.vue |
Root App component |
π | β βββ index.js |
Application entry point |
π | β βββ plugins.js |
Vue plugin configuration |
π | β βββ router.js |
Vue router configuration |
π | βββ components/ |
Vue components |
π | βββ assets/ |
Static asset files |
π | β βββ favicon.png |
Site favicon file |
π | β βββ fonts/ |
Webfont files |
π | β βββ images/ |
Image files |
π | βββ data/ |
JSON data files |
π | βββ html/ |
HTML templates for html-webpack-plugin |
π | βββ public/ |
Static public assets |
π | β βββ index.html |
Main index.html file for SPA |
π | βββ scripts/ |
Global scripts |
π | βββ styles/ |
Sass stylesheets |
π | βββ βββ config/ |
Stylesheet configuration |
π | βββ βββ tokens/ |
Design token configuration |
π | βββ βββ typography/ |
Global typography styles |
π | βββ βββ base.scss |
Global base styles |
π | βββ βββ carapace.scss |
Carapace entry point |
π | βββ βββ reset.scss |
CSS reset/normalize styles |
π | βββ βββ style.scss |
Main stylesheet entry point |
π | βββ views/ |
App views |
The production build is generated in the dist/
folder by the Webpack build system.
- Compresses images with a focus on performance
- Minifies scripts, styles, and other static assets
- Provides code splitting with Webpack dynamic imports
- Includes an offline Service Worker, so the app works offline
- Generates favicons and a PWA-compatible
manifest.json
file - Polyfills JavaScript and CSS for browser support down to IE10
The tests/
folder contains configuration and supporting files for Jest, Cypress and Backstop.
The webpack/
folder contains configuration files for Webpack. Configuration is split across different targets (build, production and analyze), with a base configuration file that is merged via webpack-merge
.
Name | Path | Description |
---|---|---|
babelPolyfill | node_modules/@babel/polyfill |
For ES2015+ support in IE10+ |
customEventPolyfill | node_modules/custom-event-polyfill |
Polyfill for window.CustomEvent |
lazysizes | node_modules/lazysizes |
Library for lazy-loaded, responsive images |
carapace | src/styles/carapace.scss |
CSS utility classes |
app | src/app/index.js |
Application source code |
scripts | src/scripts/index.js |
Entry point for global scripts (has to be loaded after lazysizes) |
These Webpack resolve aliases are registered by default, so you can go easy on dot-dot-slashes.
Alias | Path |
---|---|
~App |
src/app |
~Views |
src/views |
~Components |
src/components |
~Styles |
src/styles |
~Scripts |
src/scripts |
~Data |
src/data |
~Assets |
src/assets |
Storybook configuration
The storybook/
folder contains files for Storybook configuration.
Internal project utilities
The lib/
folder is meant for customized internal scripts and utilities that may be used on a per-project basis. (e.g. a project may require a custom parser for a specific data schema)
Design tokens are defined in src/styles/tokens/
.
Cobblestone's Webpack configuration makes it possible to use Scarab's design tokens and helper functions anywhere in the src/styles/
folder and also in Vue SFC files.
To create a new component run:
$ yarn component ComponentName
This will create the following files:
Description | Path |
---|---|
Component README | src/components/ComponentName/ComponentName.md |
Storybook stories | src/components/ComponentName/ComponentName.stories.js |
Vue SFC file | src/components/ComponentName/ComponentName.vue |
Jest component tests | src/components/ComponentName/ComponentName.test.js |
Cypress component tests | tests/cypress/integration/components/ComponentName.spec.js |
Views are defined as Vue components in the src/views/
folder.
We use vue-router
for routing. The router is configured in src/app/router.js
. This file maps routes (i.e. URLs) to router views.
Visit the Vue router documentation for more information on configuring vue-router
.
Component stories serve as content for Storybook. They live in the same folder as the component's Vue file.
- Stories are located in the
src/components/ComponentName/
folder
Refer to the Storybook documentation for how to write stories.
Component unit and integration tests can be run by either Cypress or Jest.
-
With Cypress:
tests/cypress/integration/components/ComponentName/ComponentName.spec.js
-
With Jest:
src/components/ComponentName/ComponentName.spec.js
We use Cypress for app integration and E2E tests.
- Cypress test specs are located in the
tests/cypress/integration/app/
folder
We use cypress-axe
for a11y validation. Use the provided cy.injectAxe()
and cy.checkA11y()
Cypress commands to test accessibility within components or at the application level.
We use BackstopJS for visual regression testing.
- Backstop test scenarios are defined in
tests/backstop/scenarios.js
- Backstop configuration is defined in
./backstop.config.js
Performance audits are run with Lighthouse and sitespeed.io, and need to be run on the production build.
- Run
yarn build
to generate the production build - Run
yarn serve
to serve the production build locally - Run
yarn lighthouse
to run and view a Lighthouse performance report - Run
yarn sitespeed
to run and serve a sitespeed.io performance report athttp://localhost:5000
Webpack configuration is located in the webpack/
folder. Cobblestone uses a merge strategy to handle Webpack configuration. The following configuration files are present by default:
base.config.js
β Base Webpack configurationdev.config.js
β Configuration for development serverprod.config.js
β Configuration for production buildanalyze.config.js
β Configuration forwebpack-bundle-analyzer
- Why can't I use my browser's Vue devtools extension in Storybook?
This is a known issue. As a workaround, Cobblestone uses the@vue/devtools
package, a standalone Electron version of the Vue devtools. Running$ yarn storybook
will automatically launch the Vue devtools window. To relaunch the devtools window, run$ yarn run vue-devtools
.