Slice Machine

Use Slice Machine to build models for Documents and Slices.


Slice Machine is a local Custom Type and Slice builder that connects your component code with Prismic. It also allows you to simulate your Slices in development using mock data.

One of the greatest benefits of Slice Machine is that it puts your content models in your code base, so your code is the source of truth for your data structures and you can version them with your code.

Framework compatibility

For the moment, Slice Machine is only compatible with Next.js and Nuxt projects.

Launch Slice Machine

Visit the documentation for your chosen technology to learn how to install and run Slice Machine in your project.

Custom Types

Custom Types are models for your documents.

Create a Custom Type

Go to the Custom Types tab. The Create a new Custom Type button opens a modal with the following options:

  • Repeatable or Single: Choose whether you can create multiple Documents with this Custom Type
  • Custom Type Name: A display name for the Custom Type
  • Custom Type ID: The API ID to query the Custom Type (e.g. blog-post, product-page)

After saving you'll see your new Custom Type. In the Static Zone you can add fields that only appear once per document. In the Slice Zone you can select Slices that content managers can use in this Custom Type.

To rename the Custom Type, click the pencil edit button at the top right corner of the page. Add a new name on the pop-up that will appear and save.

Use the Static Zone for metadata

In the Static Zone, add fixed fields that must appear on every document — like the Document's title and metadata. In the Static Zone, click Add a new field, then select a field from the list.

Use the Slice Zone for content

The Slice Zone is where a content manager will compose the content of the Document

The Slice Zone of the Custom Type allows you to select and group all the shared Slices you want to make available in a Custom Type.

Use tabs for organization

Within a Custom Type, you can use tabs to organize your content fields. In the Custom Type builder, click the + Add a new tab button to add a tab. Click the gear icon to edit or delete a tab.

Tabs do not affect the API response. The API delivers all fields in the data property regardless of what tab they are in.

In this example, you see an empty Slice Zone with the API ID slices:

Copy
{
  id: 'XJ45pREAACEAfEOA',
  uid: 'example-uid',
  url: '/example-uid',
  type: 'post',
  lang: 'en-gb',
  // ...
  data: {
    title: 'Example Title',
    seo_description: "Here's an example of an SEO description.",
    date: '2019-02-01',
    slices: [],
  },
}

Save locally

Once you finish editing your Custom Types, click on Save to file system. This will save the JSON structure of the Custom Type locally in the customtypes folder of your project.

Slices

Slices are website sections that you'd build as React or Vue components. Once each component is ready, you can push it to a Prismic, where your content team can compose pages.

Create a new Slice

Open the Slices tab and click Create a Slice.

Enter the name of your Slice.

Select a library for your Slices. By default, this is slices. It should match one of the the paths specified in the libraries property of your sm.json file.

After you click Save, you'll see your new Slice on the screen.

When you create a Slice, Slice Machine adds the following files to your project:

slices/ExampleSlice/index.js

The component to render the Slice (could also be a .jsx, .vue, .ts, or .tsx file)

slices/ExampleSlice/model.json

The JSON that contains the Slice model, which will be pushed to Prismic

slices/index.js

An index of your Slice components

.slicemachine/assets/slices/ExampleSlice/index.stories.js

A configuration file for Storybook if you're using it (Storybook is mostly deprecated)

.slicemachine/assets/slices/YourSlice/mock.json

A mock API response used to develop the component locally.

Adding Fields to Slices

New Slices will have a couple of default fields, which you can replace. Click on +Add a new field in the repeatable or non-repeatable zones, and give it a Name and ID (used to reference the field in the code).

  • Non-repeatable: Fields that appear only once in a Slice (for example, a title).
  • Repeatable: Fields that can be repeated more than once in a Slice (for example, Image fields for an image gallery).

Simulate Slices in development

Slice Machine generates a mock API response for each Slice to allow you to develop components in isolation without live data. The Slice Simulator is a plugin that uses an iframe running in your local project to allow you to combine the mock data with your component code. This saves you time as you don't need to add content to the Prismic repository before you can test your components.

Add a Slice variation

With Slice Machine, you can create multiple versions of your Slice. Editors choose a variation in the editor. The variations can be handled conditionally in your Slice component.

You can create multiple variations of a single Slice. You might want to add an extra field, change the position of the image with the CSS, or present an image gallery in different views.

Click on the dropdown arrow that already shows the Default Slice settings. To add a Slice variation to your Slice, select + Add new variation. It will open a pop-up to add more information:

  • Variation Name: Enter the name of a variation. The variation name will appear in the variations dropdown in Slice Machine and in the page editor in Prismic.
  • Variation ID: This is generated automatically based on the variation name and will appear in the variation key in the API response.
  • Duplicate from: Choose the Slice from the dropdown from which you want to duplicate the variation.

Once your variations are set up, you can access them in your components in slice.variation.

Slice Screenshots

Slice Machine allows you to upload images of your Slices so that content managers will know what each Slice looks like when editing content.

You can generate automatic screenshots by clicking Take Screenshot in your Slice.

You can add a custom screenshot by clicking Custom screenshot in your Slice variation and uploading an image file named preview.png.

If you do not specify a screenshot, a placeholder image will appear in the Prismic editor.

Save locally

Once you finish editing your Slices, click on Save to file system so they can exist locally in the slices folder of your project. This allows you to version your Slices as your project evolves using a code versioning service like GitHub or Bitbucket.

Slice Libraries

Slice Machine chooses a default slices folder to save Slices. To add another collection of Slices to your project:

  1. Add a new folder in your project directory.
  2. Open the sm.json file in your project, then add or modify the path to the new folder inside libraries. For example:
Copy
{
  "apiEndpoint": "https://your-repo-name.cdn.prismic.io/api/v2",
  "libraries": [
    "@/slices",
    "@/my-second-slice-lib"
  ],
  "_latest": "0.1.0",
  "localSliceSimURL": "http://localhost:3000/_simulator"
}

After that, you’re able to select the new library from the Target Library dropdown when adding a new Slice with the + button.

Custom component templates

You can modify the default component template generated when you create a new Slice.

There can be many use cases where you might need to customize the default Slice template, such as modifying the component HTML structure, generating post CSS files, or even adding your typings if you use TypeScript.

To do this, create a folder at the base of your project called .prismic. Then, inside this folder, add another folder called slice-template which should contain at least index.(js|vue|tsx) and model.json files. The folder name will let Slice Machine know this is the new template.

Here's an example of the file structure:

Copy
.prismic / slice-template
├── index.tsx
└── model.json

Add variables between curly brackets for the name and the ids in the model.json file. Slice Machine will replace them with the details of each newly created Slice. Here's an example:

Copy
{
  "id": "{{componentId}}",
  "type": "SharedSlice",
  "name": "{{componentName}}",
  "description": "Text",
  "variations": [
    {
      "id": "{{variationId}}",
      "name": "Default",
      "docURL": "...",
      "version": "sktwi1xtmkfgx8626",
      "description": "Text",
      "primary": {
        "content": {
          "type": "StructuredText",
          "config": {
            "label": "Text",
            "placeholder": "Text with rich formatting",
            "allowTargetBlank": true,
            "multi": "paragraph,preformatted,heading1,heading2,heading3,strong,em,hyperlink,image,embed,list-item,o-list-item,rtl"
          }
        }
      },
      "items": {},
      "imageUrl": "https://images.prismic.io/slice-machine/621a5ec4-0387-4bc5-9860-2dd46cbc07cd_default_ss.png?auto=compress,format"
    }
  ]
}

Fields

Field settings

You can configure your Field settings by clicking on the pencil icon of any field. In the Field Model tab, you can edit the following field settings:

  • Label: The Label for content creators. Defaults to the Field type.
  • API ID: The name of the property on the API, e.g. buttonLink, description
  • Placeholder: Placeholder text help guide content managers

Code Snippets

Slice Machine provides suggested code snippets based on your framework for each of the fields that you add. Copy-paste the snippet directly into your Slice component to use the data.

These code snippets are optional. You can also code the Slice manually.

Customize mock data

Slice Machine generates mock data for each Slice and its Fields so you can simulate how a Slice will look with live content. Customizing this mock data allows you to closely match your use case and test other possible use cases.

In the Mock Config tab, you'll be given different options to output different mock data patterns so you can see how components look with multiple variations or with a pattern that matches your design.

Push changes to Prismic

Once you're done creating and editing the content modeling of your Custom Types and Slices, go to the changes page. Click on Push to Prismic to send the models to Prismic and make them available in the repository UI when creating a new document.

If your Slices are already connected to a Custom Type(s), it will be updated on all Custom Types when you push an update on the Slice level.

Legacy Slices

Non-shared Slices or legacy Slices, at the moment, can not be edited from Slice Machine. Although they are represented in the Custom Types, to give the developer more information on the contents of existing Custom Types.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.