How To Publish Your Library

So you've created a library and of course you'll want to use it in different project or share it with other Slicemachine users.

To make your library available to use you will need to register it on NPM but first you will need to make sure it meets the requirements below:

Project structure

In order for a folder to become an actual SliceMachine library, it needs to follow a certain structure, that may be accommodated to your requirements but still follows some conditions:

Starter structure:
├── .storybook # Design guide config
├── slices # actual components
│   ├── ComponentName # see "slices" section
│   ├──  ...
├── index.js # exports * from './slices'
├── sm.json # auto-generated, see "bundling" section
├── sm.config.json # SliceMachine config

1. Slices

Your Slices will need to have the following files in PascalCased named folder, with a minimum 2 words starting with capital letters, to be valid. Luckily the --create-slice command creates these files as a template for you:

  • an index.storie.js file
  • an index.[js|ts|vue] file (the actual component)
  • a model.json file, that contains the slice definition
  • a mock.json file, that contains a valid API response
  • a preview.png file, that displays the preview of the component

2 - sm.config.json

A configuration file that helps SliceMachine bundle script understand how it should build the library.

{
  "libraryName": "Vue essentials",
  "framework": "nuxt",
  "gitUrl": "//github.com/prismicio/vue-essential-slices",
  "pathToLibrary": "src",
  "dependencies": [],
  "css": ["vue-essential-slices/src/styles/styles.scss"],
  "script": [{
    "src": "https://cdn.polyfill.io/v2/polyfill.min.js?features=Element.prototype.classList"
  }, {
    "src": "https://cdn.jsdelivr.net/npm/focus-visible@5.0.2/dist/focus-visible.min.js"
  }],
  "devDependencies": ["node-sass", "sass-loader"]
}

libraryNameframework and gitUrl are mandatory. Other info (like pathToLibrary) helps SliceMachine bundler to find your slice definitions. dependenciescssscript and devDependencies being information picked up by SliceMachine CLI to kickstart a project.

Most of the time, you would be fine with this:

{
  "libraryName": "Name of your Lib",
  "framework": "nuxt|next",
  "gitUrl": "...",
  "pathToLibrary": "src"
 }

Bundling

Every time you publish your library on NPM, Prismic servers download your library definition file. This definition file is what the writing room uses to select/preview your slices. In order to generate a valid JSON definition for your library, add our sm-commons development package and run its bundle script every time you want to publish a new version of your library:

npm i --save-dev sm-commons

Then, add this script line to your package.json file (subject to change because I don't know how to make it appear as a bin script😭) :

"scripts": {
    "bundle": "node ./node_modules/sm-commons/scripts/bundle"
}

👆 This script is in active development and subject to lots of change. Make sure you update it as often as possible. A lot of effort will be made to help you understand if and why a folder structure is considered invalid. Feel free to read the script of course, it's really simple atm.

Here is the structure of our actual SM definition file:

{
   "libraryName":"Vue essentials",
   "framework":"nuxt",
   "packageName":"vue-essential-slices",
   "gitUrl":"//github.com/prismicio/vue-essential-slices",
   "pathToLibrary":"src",
   "dependencies":[],
   "css":["vue-essential-slices/src/styles/styles.scss"],
   "package": {},
   "slices": { "call_to_action": {} 
}

Publish to NPM

You will need to push your project to Github and then follow this hand guide to registering your Git repo on NPM.

Using the library in your project

Once you do this you'll be able to setup other projects with your library as the default instead of vue-essential-slices by running the following command: 

prismic sm --setup --library my-npm-package

Resources

9 Rue de la Pierre Levée, 75011 Paris