Publish Your Library

Beta

These docs rely on Slice Machine, which is in active development and subject to change. Content Relationships are not currently supported with Slices.

By the end of this article you will learn how to publish your Slice Machine component Library for others to use.


So you've created a library, and of course, you'll want to use it in different projects 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:

Copy
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.vue file (the actual component)
  • model.json file, that contains the slice definition
  • mock.json file, that contains a valid API response

2. sm.config.json

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

Copy
{
  "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:

Copy
{
  "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
  • Yarn
Copy
npm i --save-dev sm-commons
Copy
yarn add sm-commons --dev

Then, add this script line to your package.json file (subject to change) :

Copy
"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 at the minute.

Here is the structure of our actual SM definition file:

Copy
{
   "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 handy 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: 

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

Resources


Related Articles


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.