slice-machine-ui v1.0 Migration Guide

This is a guide for upgrading slice-machine-ui v0.7 to slice-machine-ui v1.0.

Version 1 has one significant change: the config file has been renamed from sm.json to slicemachine.config.json. The properties of the config file have also changed.

Update slice-machine-ui package

First, upgrade to version 0.7 if you aren’t already using it:

npm install slice-machine-ui@^0.7

Then, run Slice Machine to ensure that everything is working normally.

Next, run this command to upgrade slice-machine-ui to version 1.0:

npm install slice-machine-ui@latest

Run Slice Machine, which will automatically run migration steps to upgrade your project.

Handling breaking changes

Replace sm.json with slicemachine.config.json

A slicemachine.config.json file will be created the first time you run Slice Machine. The generated file will automatically include your options from sm.json.

If you have any custom properties in sm.json, migrate them to the newly-created slicemachine.config.json file.

Search your project for references to sm.json and replace them with slicemachine.config.json.

- import sm from './sm.json'
+ import sm from './slicemachine.config.json'

Replace references to apiEndpoint from sm.json with repositoryName anywhere that you use them. In prismic.createClient(), you can pass repositoryName instead of apiEndpoint. If you need the endpoint, you can use prismic.getEndpoint(repositoryName).

  import sm from './slicemachine.config.json'

- const client = prismic.createClient(sm.apiEndpoint, {
+ const client = prismic.createClient(sm.repositoryName, {
    routes,
    ...config,
  })

Once slicemachine.config.json is updated and your project no longer references sm.json, delete sm.json.

Remove prismicio.d.ts from tsconfig.json

If you’re using TypeScript, remove "./.slicemachine/prismicio.d.ts" from the include array of tsconfig.json.

Notable changes

sm.json is now slicemachine.config.json

The root config file for Slice Machine has a new name. When you run Slice Machine 1.0, it will check to see if you have a sm.json file and automatically generate a slicemachine.config.json file if there is none.

sm.apiEndpoint replaced with sm.repositoryName

slicemachine.config.json requires a repositoryName property instead of an apiEndpoint property. The repositoryName will be safer and easier to handle.

sm.adapter is now required

Your slicemachine.config.json file now requires a new property called adapter. This property specifies an npm package that Slice Machine will use to integrate with your frameworks. The first two officially-supported adapters are @slicemachine/adapter-next and @slicemachine/adapter-nuxt.

.slicemachine folder is gone and prismicio.d.ts has moved and changed its name

We’ve removed the .slicemachine folder altogether. In previous versions of Slice Machine, this folder stored the mocks for your slices, but those are now stored alongside the slice component.

.slicemachine used to contain the types file, prismicio.d.ts. You can now move that file to the root level of your project and rename it prismicio-types.d.ts. That also means that you can remove this line from your tsconfig.json:

  {
    "include": [
-    "./.slicemachine/prismicio.d.ts"
    ]
  }

With your types located at the root of your project, TypeScript should find them without issue.

Custom component templates are gone

As we move to a new plugin-based framework integration, we are removing custom component templates. We’ll release more information about component templates later in the year.

Mock config is gone

Now that the slice simulator can simulate most fields, there is much less need to configure mocks. Instead, you can create your own mocks in the simulator. As such, we’ve removed mock configurations.

@slicemachine/init is much smoother

We have completely revamped the init command for Slice Machine. The init command will now create your slice simulator route, suggest a repository name intelligently, and install dependencies in the background for less wait time.