Developers / Slice Machine

Slice Machine

Use Slice Machine to build models for pages and slices.

Slice Machine is a local development tool for building types and slice models in sync across your codebase and your Prismic repository. Slice Machine puts your content models in your codebase, so your code serves as the source of truth for your data structures. With Slice Machine, you can version and simulate your content models locally.

Launch Slice Machine

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

Next.js
Nuxt
SvelteKit
Nuxt 2 (Legacy)

Types

Types are models for your documents.

What is a Type?

Learn more about types and how to configure them.

Creating

To create a new type, go to the page types or custom types tab. The Create button opens a modal with the following options:

  • Name: A display name for the custom type
  • API ID: The ID to query the custom type (e.g. blog-post, product-page)

After saving you'll see your new type and you can start adding fields.

Use the static zone for metadata fields, like the document's title and Open Graph image.

Page types store content in the slice zone. The slice zone houses rearrangeable, reusable website sections called slices. (Read more about slices below.)

Tip: Use tabs for organization

Within a type, you can use tabs to organize your content fields. In the type builder, click the + Add a new tab button to add 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.

Saving

As of version 1.23, Slice Machine automatically saves on change.

The JSON structure of the type is saved locally in the customtypes folder of your project.

Once your models are ready, push them to Prismic (see the section below).

Deleting

To delete a type, open the types list and click the ⋮ three-dot menu and select Delete. If the type has any associated documents in the repository, you will be prompted to confirm the deletion of those documents.

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.

What is a Slice?

Learn more about slices and how to configure them.

Creating

Open the slices tab and click Create a slice.

Select a library for your slices. By default, this is ./slices. It should match one of the paths specified in the libraries property of your slicemachine.config.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 .ts or .vue file)

slices/ExampleSlice/model.json

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

slices/ExampleSlice/mocks.json

A mock API response used to develop the component locally.

slices/index.js

An index of your slice components

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

Simulating

As you develop your slice, you can simulate it with mock content. The simulator has a sandboxed editor so you can test the editing experience. This feature is in active development, and fields will be added progressively.

Adding variations

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.

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.

Adding 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. Upload or copy-paste your screenshots into your slice in Slice Machine.

Saving

As of version 1.23, Slice Machine automatically saves on change.

The JSON structure of the slice is saved locally in the slices folder of your project.

Once your models are ready, push them to Prismic (see the section below).

Deleting

To delete a slice, open the slices list, click the ⋮ three-dot menu on the slice you want to delete, and select Delete. This will not remove the slice from documents that use it. You will need to do this manually.

Versioning

You may want to roll back changes to your models. We recommend using git for versioning.

Here are some useful git commands for versioning files and rolling back changes in Slice Machine:

Copy
# Check git status
git status

# Revert changes for a specific file
git checkout -- path/to/file

# Discard all uncommitted changes
git reset --hard <commit-hash>

# View commit history
git log

# Revert to a specific comit
git revert <commit-hash>

Pushing changes

Once you're done creating, editing or reverting changes to the content modeling of your types and slices, go to the changes page. Click on Push to Prismic to send the models to Prismic so that editors can use them in the Page Builder.

Fields

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

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.

Configuration

Slice Machine projects have a required slicemachine.config.json file at the project root. This file has the following properties:

repositoryName

Required

Your Prismic repository name, formatted in kebab case (e.g. "example-prismic-repo")

adapter

Required

An npm package that exports an adapter make Slice Machine compatible with your framework (e.g. "@slicemachine/adapter-nuxt", "@slicemachine/adapter-next")

libraries

Required

An array of directories where your slices are stored (e.g. ["./slices"])

Legacy slices

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

TypeScript

As of version 0.51, Slice Machine can generate TypeScript types for your slices and types automatically thanks to prismic-ts-codegen. Generated types are used to automatically infer the TypeScript type of documents you query with @prismicio/client. They can also be used to type other parts of your project.

In most cases, your Prismic content will be fully typed automatically:

Copy
import * as prismic from '@prismicio/client'

const client = prismic.createClient('your-repo-name')
//    ^ Contains references to document types

const home = await client.getByUID('page', 'home')
//    ^ Typed as PageDocument

You can also import generated types from @prismicio/client in TypeScript projects.

Copy
import { Content } from "@prismicio/client";

const blogPost: Content.BlogPostDocument = ...;
const testimonialSection: Content.TestimonialSectionSlice = ...;

Alternatively, you can also use them through JSDoc in JavaScript projects.

Copy
/** @type {import("@prismicio/client").Content.BlogPostDocument} */
const blogPost = ...;

/** @type {import("@prismicio/client").Content.TestimonialSectionSlice} */
const testimonialSection = ...;

Tracking

Slice Machine tracks some user behavior to help improve the product. All tracking is anonymous. To disable tracking, create a .prismicrc file at the home directory or at the root of your project and input this content:

Copy
telemetry=false

Simulate slices

Slice Machine includes a simulator that previews your slices with mock data in development. The simulator also enables live previews in the new Alpha Page Builder.

In order to run, the simulator depends on a Slice Machine adapter. We currently have three adapters:

If you see an error in the simulator, try these troubleshooting steps:

  • You should have two servers running: one for your website in development and one for Slice Machine. Ensure both are running. If you are using an official Prismic starter, npm run dev will run both servers concurrently.
  • Ensure that your Slice Machine adapter is installed and configured correctly. (See above.)
  • You should have a page component for the simulator, configured as described above. The page component for your simulator should be named slice-simulator.js|jsx|tsx|vue (unless you have specified a different route in your configuration file).
  • Your slicemachine.config.json file should have a localSliceSimulatorURL that points to the route for your simulator. Check that the property exists and the route is correct.
  • If you have multiple slice libraries, there could be a namespace conflict between slices from the different libraries. Ensure your slices have unique names and IDs.
  • It's possible that there is a global error in your website. Check for errors in your app.
  • It's possible that either a slice component has no visible output or that it is throwing an error that your framework hasn't caught. Check that your slice components render properly.
  • It's possible that there's a bug in Slice Machine or the simulator. Submit an issue on GitHub.
Can't find what you're looking for?

Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.

Adjust cookie settings