This content originally appeared on Kitty Giraudel and was authored by Kitty Giraudel
I spent the afternoon migrating a pretty large studio from version 2 to version 3. It was pretty challenging, rewarding and frustrating at time so I thought I’d jot down my thoughts.
Aliases
Last year, I wrote about sharing code between a Sanity studio and the app it relates to by configuring Webpack aliases. Sanity v3 is no longer built on top of Webpack though; it uses Vite which uses Rollup.
It took me a long time to figure out that the path aliasing configuration needs to be defined in the sanity.cli.js file and not the sanity.config.js file. I feel like this information could be mentioned in the migrating from v2 documentation.
import path from 'path'
import { defineCliConfig } from 'sanity/cli'
export default defineCliConfig({
api: {},
vite: config => {
if (!config.resolve) config.resolve = {}
if (!config.resolve.alias) config.resolve.alias = {}
config.resolve.alias['@'] = path.resolve(__dirname, '..', 'src')
return config
},
})JSX files
Any file which ends up including JSX — either directly or indirectly — now needs to have the .jsx extension and I’m not exactly sure why. It’s conventional if anything, and wasn’t necessary in version 2. Having to rename all my files because of an implementation detail seems rather unnecessary.
Styling
Style overrides are no longer possible besides just replacing some CSS custom properties with a custom theme. This is a shame because I used to overwrite some styles to make the studio more friendly/accessible.
For instance:
button:not(:disabled) {
cursor: pointer !important;
}Inconsistent context
Unlike other configuration functions (document.actions, document.newDocumentOptions, document.productionUrl), the studio.components.toolMenu configuration function does not receive the context, which means it is not possible to get the current user.
Ideally we could do:
const isAdmin = currentUser =>
currentUser?.roles.some(role => role.name === 'administrator') ?? false// This does not work: `context` is undefined.
{
studio: {
components: {
toolMenu: (props, context) => {
const tools = isAdmin(context.currentUser)
? props.tools
: props.tools.filter(tool => tool.name === 'default')
return props.renderDefault({ ...props, tools })
}
}
}
}This makes it very inconvenient to customize the available tools based on the user’s role. Right now we have to hack things together by storing the current user on the window object in some other function, which is really awkward and prone to fail.
Similarly, the schema.types configuration does not accept a function but an array of types. A function would make it possible to get the context, particularly the current user, to condition the search engine based on the user’s role.
// This does not work: `schema.types` expects an array, not a function.
{
schema: {
types: context => {
return schemaTypes.map(entity => {
if (entity.type === 'document' && !EDITOR_TYPES.includes(entity.name)) {
return {
...entity,
__experimental_omnisearch_visibility: isAdmin(context.currentUser),
}
}
return type
})
}
}
}New order plugin
Sanity never had a built-in way to order documents within the studio. The general expectation is that documents should be programmatically sorted via the API based on their fields instead of manually in the interface.
Fortunately, there was the sanity-plugin-order-documents plugin that did just that. Unfortunately, it was a v2 plugin, and will not be migrated to v3. Sanity shipped its own official plugin for v3, except it’s much more awkward.
The new plugin documentation is very thin to start with, which is in stark contrast with the rest of the Sanity environment which is generally exceptionally well documented.
Perhaps more problematic: while the old plugin added another page entirely to reorder certain document lists (as illustrated here), the new one injects new menus within the main desk tool which makes for an awkward experience.
For instance if you have an orderable “Category” entity type, you end up with a second menu called “Ordering Category” below it (or whatever you call it). And I’d be fine with it if that menu was there only to reorder entries, but that’s not the case: you can do full documents edit within that menu as well, which means you now have 2 places to do the same thing. I’m not sure what limitation they were fighting to cause the interface to be skewed like this.
New media plugin
The new official media plugin which is supposed to replace the incredible media library community plugin forces the dark theme while the rest of the studio correctly adapts to the current theme (reported in #86).
Broken readonly fields
As of version 3, the readOnly property no longer works if the field lives inside a fieldset — regardless of whether the fieldset is collapsed or not. It used to work fine in version 2.
On the bright side
As you can see, it’s sometimes a little rough around the edges when doing things that are not super basic. That being said, version 3 brings a lot of super nice improvements. In no particular order:
- The configuration being authored in JavaScript instead of JSON is so much more enjoyable to work with. I genuinely think JSON is incredibly ill-suited for configuration files (starting with the absence of comments).
- No more weird
part:import paths, which is so much cleaner, nicer and easier for inter-operability with other tools. This monkey-patching of the Node resolution algorithm was madness, and I’m glad to see it gone. - The
document.productionUrlconfiguration intended to set up previewing systems can now be asynchronous, which was a pretty frustrating drawback in v2 requiring weird hacks.
I’ll keep updating this article as I learn more about v3.
This content originally appeared on Kitty Giraudel and was authored by Kitty Giraudel
Kitty Giraudel | Sciencx (2023-01-22T00:00:00+00:00) Thoughts on Sanity v3. Retrieved from https://www.scien.cx/2023/01/22/thoughts-on-sanity-v3/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.