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.
Visit the documentation for your chosen technology to learn how to install and run Slice Machine in your project.
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.
Once you finish editing your types, click on Save to file system. This will save the JSON structure of the type locally in the customtypes folder of your project. This will not save the changes to your Prismic repository. See how to push your changes to Prismic below.
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 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.
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 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).
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.
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.
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.
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 will not save the changes to your Prismic repository. See how to push your changes to Prismic below.
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.
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.
Once you're done creating and editing 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.
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"])
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.
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:
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 PageDocumentYou can also import generated types from @prismicio/client in TypeScript projects.
import { Content } from "@prismicio/client";
const blogPost: Content.BlogPostDocument = ...;
const testimonialSection: Content.TestimonialSectionSlice = ...;Alternatively, you can also use them through JSDoc in JavaScript projects.
/** @type {import("@prismicio/client").Content.BlogPostDocument} */
const blogPost = ...;
/** @type {import("@prismicio/client").Content.TestimonialSectionSlice} */
const testimonialSection = ...;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:
telemetry=falseSlice 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:
- @slicemachine/adapter-next for Next.js
- @slicemachine/adapter-nuxt2 for Nuxt 2
- @slicemachine/adapter-nuxt for Nuxt 3
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 devwill 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.jsonfile should have alocalSliceSimulatorURLthat 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.
Was this article helpful?
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.