README

Develop and work with Prismic slices, locally.

Slice Machine

As a developer tool, the main goal of Slice Machine is to perfect the process of working with a CMS while developing components locally.

1. Build reusable website sections

We call them Slices. Create and iterate on your Slices within your codebase, without going back and forth to a web app.

It takes a few seconds to generate components with corresponding data models. Everything is stored and versioned right inside your code.

2. Preview your components locally

While you build your components, you'll need to preview them. Slice Machine generates updated mocks to display content in the context of your app — without querying any remote content.

If you already use Storybook, Slice Machine generates stories for each of your Slices.

3. Ship your library to a page builder

Once you're done creating your components locally, publish them to Prismic. You get a full-fledged online content editor, tailored to your components' data models. Content editors can preview Slices from there and create pages without any help!

Install

npx @slicemachine/init

Install required deps

# using React/Next
npm i --save next-slicezone prismic-reactjs
# or using Vue/Nuxt
npm i --save vue-slicezone nuxt-sm

Nuxt users: you will have to add nuxt-sm to your nuxt.config.js modules section.

Documentation

For full documentation, visit the the official Prismic documentation.

Launch Slice Machine

You should now be ready to launch the plugin:

npm run slicemachine

Once the CLI gives you information regarding your project, open the given localhost address to start working.

Previewing Slices

Once you are familiar with the plugin and you created a Slice, you should notice that a folder has been created inside your slices library. It contains a component code and its Prismic data model.

You should also notice that a .slicemachine folder has been generated. It contains (notably) the generated mocks for each of your Slices.

Import both your component and its mock in a page to preview it:

import { MySlice } from '../slices'
import MySliceMocks from '../.slicemachine/assets/slices/MySlice/mocks.json'

// In case of Next.js
const Page = () => (
  <div>
    <MySlice slice={MySliceMocks[0]} />
  </div>
)

Note that MySliceMocks is an array of Slice variations. You get 1 Slice mock per variation.

Using Storybook

Add the localhost port of your Storybook instance to sm.json:

{
  "apiEndpoint": "...",
  "storybook": "http://localhost:6000"
}

In .storybook/main.js, import our getStoriesPaths helper and use it inside stories array:

const { getStoriesPaths } = require('slice-machine-ui/helpers/storybook')

module.exports = {
  // ...,
  stories: [...getStoriesPaths()]
}

Run Storybook. You should now be able to access it from Slice Machine, and screenshots will be taken from there everytime you save/push your Slices.

Publishing your library

Once you're happy with the result, it's time to publish it to Prismic. Note that if you want to be able to use a Slice in one of your pages (Custom types), you will have to click on "Add slices" in the Custom types editor and select the Slices to be used.

Pushing a Custom type to Prismic will push all the Slices that are linked to it.

Inside Prismic.io, you should now be able to create documents and use the Slices you defined locally using Slice Machine 🎉

Next step

Connect your pages to Prismic!

Next user? Check this page out! Nuxt user? Check this page instead.

If you use another technology, it's probably listed there: https://prismic.io/docs

Have fun!

Contributing

Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Prismic developer community!

Asking a question: Open a new topic on our community forum explaining what you want to achieve / your question. Our support team will get back to you shortly.

Reporting a bug: Open an issue explaining your application's setup and the bug you're encountering.

Suggesting an improvement: Open an issue explaining your improvement or feature so we can discuss and learn more.

Submitting code changes: For small fixes, feel free to open a PR with a description of your changes. For large changes, please first open an issue so we can discuss if and how the changes should be implemented.

License

   Copyright 2013-2021 Prismic <contact@prismic.io> (https://prismic.io)

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

sm-commons

Usage no npm install needed!