Getting set up

Building a site with Bookshop requires a specific directory structure that lives alongside your website, and an Eleventy plugin to discover and use components.

As a useful reference, the Eleventy Bookshop Starter repository contains a simple site fully integrated with visual editing. Browsing the code and the file structure of the starter site can be helpful to solidify the concepts covered in this guide.

Prerequisites#

Bookshop requires Node >= 16 to be installed on your machine.

Creating your Bookshop directory#

Bookshop requires that your component files live in a specific directory structure, which allows for components to be discovered automatically.

The easiest way to get started is to run Bookshop's init command. This should be run alongside your website source files:

Command line

copied

npx @bookshop/init --new _component-library --framework eleventy

After running this command, the following directory structure will be created:

_component-library/
├─ bookshop/
│  └─ bookshop.config.cjs
├─ components/
│  └─ sample/
│     ├─ sample.bookshop.yml
│     ├─ sample.eleventy.liquid
│     └─ sample.scss
└─ shared/
   ├─ eleventy/
   │  └─ page.eleventy.liquid
   └─ styles/
      └─ global.scss

Here's a quick run-through of what has been generated:

bookshop/bookshop.config.cjs#

This houses the configuration for your Bookshop project, in this case instructing Bookshop to use the @bookshop/eleventy-engine package for any live component rendering.

components/#

This is where you will write your component files, a sample component has been added for you.

shared/eleventy/#

Any non-component files that you want to be able to use when live editing can be placed here. A page helper has been created, which helps render arrays of components.

shared/styles/#

Optionally, any SCSS files in this directory will be imported alphabetically before component SCSS files. These are used on both the site, and the component browser.

Connecting Bookshop to Eleventy#

To connect Bookshop and Eleventy, install the @bookshop/eleventy-bookshop plugin from npm:

Command line

copied

npm i --save-exact @bookshop/eleventy-bookshop

Command line

copied

yarn add --exact @bookshop/eleventy-bookshop

Within your Eleventy config, import this plugin and specify the path to your Bookshop project.

.eleventy.js

copied

const pluginBookshop = require("@bookshop/eleventy-bookshop");

module.exports = function (eleventyConfig) {
  // ...

  eleventyConfig.addPlugin(pluginBookshop({
    bookshopLocations: ["_component-library"],  
    pathPrefix: '', 
  }));

  // ...
};

Make sure that bookshopLocations points to the component library you just created, relative to your Eleventy source.

If you specify multiple paths, components will be merged from all sources that exist.

The pathPrefix provided must match the pathPrefix configured in your .eleventy.js configuration.

If you aren't using pathPrefix, this option can be omitted.

Now that Bookshop is installed and your Eleventy site can access it, we can look at creating and using components.