Type utility for blok schema definitions

[shabab477]

Bit of background

In our team we are using the approach of defining the blok schemas in the code rather than navigating through the UI. This has the benefit of version controlling the schema definitions and also provides transparency, because then we don't have to look at the Storyblok dashboard to verify what the configuration looks like. We use the CLI tool to CRUD the schema definitions.

Problem

Now there are two problems that are being faced here:

• Because Storyblok doesn't provide a type definition for the schema itself, so we made our type definition of the blok schema. This is not ideal because every time Storyblok changes their API specs we need to be aware of changing the schema itself. If the spec changes and our type definition don't then we see no type errors in our implementation of the blok schema itself but keep getting 422 status code from the storyblok API because its expected payload did change. To add salt to injury, sometimes the docs aren't clear on which Schema to follow. For example, here you shall see a schema type saying Multi-Option but then here the Multi-Option is aliased as options.

• On the other end we love type definitions and find the initiative from Storyblok cli to pull the type definitions of the blok helpful. However when multiple people are working, i,e: creating or updating their schemas the type definitions changes. During merge conflict resolution/reviewing it is hard to identify what actually changed or the code was refactored correctly. So what happens is someone runs into compilation issues in their pipeline, deletes the whole file and pulls the defs again. And then prays that the team doesn't modify the fields of their schema anymore.

Expected Behavior

• To solve problem one, it would be extremely helpful to have schema definitions for the blok itself. Something like type SbBlokSchema which is the single source of truth and always ensures it is up to date with what the Management API end points expect.

• To solve problem two:

  • Since we are using the code first approach, the idea of pulling the schema can be avoided altogether. Having a utility like FromSbBlokSchema<T extends SbBlokSchema> should be good to infer the properties, the fields and whatever is necessary for the developers.
  • Another solution can be(not a big fan of this since it solves the problem half way) is to make the CLI pull schema create separate *.d.ts files for each type definitions. This will avoid merge conflicts arising from spaces or new lines but at least it will be easier to review the changes.

Current Behavior

• No type definitions for the schema definitions
• No type utility to extract type from the schema definitions

If you like the ideas and find it aligned with the Storyblok teams' vision(if there is any) of having more types then I can have a discussion with my team to assign some helpful hands.

[alvarosabu]

Hi @shabab477 thank you for opening such detailed feedback. We are aware of it and are working right now on shaping up what will be the next major version of the client, and the main focus will be proper typing and generics on the table.

Would you be interested in helping us try out the new approach when we implement it to see if it covers your case completely?

Thanks a lot