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.

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

Custom Types are models for your documents.

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.

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.

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.

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:

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 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.

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:

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. The following fields are currently available in the simulator editor:

• Title
• Rich Text
• Boolean
• Number
• Image
• Select
• Key Text

More fields will be added over time.

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.

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 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.

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 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:

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

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:

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:

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.

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.

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.

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.

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

Type generation gets enabled automatically if @prismicio/types is part of your project’s dependencies. If it’s not yet, install it with your package manager. Then type generation will be enabled automatically.

Once enabled, types are generated whenever you make an edit in Slice Machine to your Slices and Custom Types. Types are saved at .slicemachine/prismicio.d.ts.

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

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

To disable automatic type generation, update the sm.json file with the generateTypes option and delete .slicemachine/prismicio.d.ts if present.

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.
• 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|ts|tsx]. Check that everything is in order.
• Your sm.json file should have a localSliceSimulatorURL that points to the route for your simulator. Check that the property exists and the route is correct.
• You should have the @prismicio/slice-simulator-react package installed. Check that it's present in your package.json and try re-running npm install.
• If you have multiple Slice libraries, there could be a namespace conflict between Slices from the different libraries. Ensure your Slices have unique names.
• 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.