pris-types
Framework-agnostic library to generate Prismic models, from code.
Obviously, the name pris-types
is derived from prop-types
and in a similar fashion, offers a declarative way to document (and generate) the intended shape of data passed from Prismic to your components.
Check out the docs: https://pris-types.vercel.app!
Quick Start
First of all, please note that pris-types
is extremely alpha. At the moment, it:
- breaks with Vue.js files
- has not been extensively tested
- is subject to major changes
Install
If you still want to try it out (and you should!), this is how you can get started:
yarn add -D pris-types@alpha
or
npm i --save-dev pris-types@alpha
Of course, alpha
is an adventurous choice but hey, if you're here you're probably an adventurer
Once this is done, you should add pris-types-watch
script to your package.json
.
For example, this line comes from my own test project:
{
scripts: {
"watch": "pris-types-watch --lib ./slices"
}
}
Arguments
--lib
(required)
As you could see from the previous example, the watcher expects a --lib
argument to be passed.
It should point to a library you defined in your sm.json
file. In you need more than one library, please raise an issue on Github.
--port
By default, the watcher connects to the builder and saves on port 9999
.
To change that, simply pass a --port
argument to the script.
Your first Model
Once the script is running, open your favourite editor and paste this portion of code there:
import { PrisTypes } from 'pris-types'
export const Model = PrisTypes.shape({
__meta: { title: 'My Slice', description: 'A simple slice' },
defaultVariation: PrisTypes.variation({
primary: {
title: PrisTypes.Title,
description: PrisTypes.RichText({
placeholder: "short length text please"
}),
},
items: {
color: PrisTypes.Color
}
})
})
On save, if everything went well, you should see new files next to your slice:
a model.json
file and a mocks.json
file
Your first Mock config
SliceMachine generates mocks for each of your slices. This is a powerful feature as it helps you build your components the way they will be used, without having to actualy create documents and query them. To refine the kind of data you receive, you can pass a optional mock configuration object:
import { PrisTypes } from 'pris-types'
export const Mocks = {
defaultVariation: {
items: {
color: PrisTypes.Color.Light()
}
})
})
How it works
Sometimes, understanding how things work can help both the debugging and the fun.
The first thing that pris-types-watch
does is quite obvious: it takes the --lib
argument
you passed and looks for all slices there (your-lib-path/[SliceName]/index.(js|ts|vue)
).
Then, and everytime one of these files changes, a Babel plugin is called.
With the help of Babel transform function, this plugin does one thing: it looks for keys Model
and Mocks
and extracts them as AST objects. Then, some checks are done: do the keys exist, do they look right?
Alright, everything looks good. A second function is then called. Its role is to take your input and to evaluate it.
You read that right: it runs eval
on your code. Several reasons exist for this, the main one being that it allows the plugin to create the right context,
in which your code will be executed.
Once this function is called, a payload is created. It contains the model
that Prismic expects and a mockConfig
object
that will tell the builder how you want your mocks to be generated. It then calls its save function (http://localhost:9999/api/update
).
If you configured everything properly, the builder should then do its job:
- Save the newly created model to FileSystem as JSON
- Store the mock configuration in
.slicemachine/mocks.json
- Use this config to generate an actual mock and store it along your slice
- Regenerate your Storybook story and take a new screenshot of it
Voilà! Once you made all your changes and checked that everything worked as expected,
you can push everything to Prismic and start changing your content