1.0 Roadmap

[ricokahler]

Edit May 9th, 2021: This issue now represents the 1.0 roadmap!

There has been a lot of development since the first release of this lib and the next version of this lib has a lot coming. The project will now be divided up into different sub-packages:

• @sanity-codegen/schema-codegen — code generation and extraction for sanity schemas
• @sanity-codegen/groq-codegen — code generation and extraction or GROQ queries in code
• @sanity-codegen/client — thin wrapper client that augments @sanity/client for GROQ codegen
• @sanity-codegen/types — a separate, no-deps package for shared types
• @sanity-codegen/cli — a new CLI powered by oclif
• @sanity-codegen/jamstack-client — a specialized client intended for use in jamstack apps. Will include preview mode logic

Edit July 12th, 2021: See here 👉 https://github.com/ricokahler/sanity-codegen/issues/5#issuecomment-877925182

✨ Features

Here are a list of features that are slotted for 1.0:

Schema Codegen:

• [x] schema extractor — a new API for extracting sanity schemas from sanity studio setups (shims our a browser environment)
• [ ] schema normalizer/validator (in-development) — a new API for taking in sanity schemas and normalizing them for easier use in schema codegen
• [x] refined schema codegen — a re-write of the schema codegen using the new normalizer.
• [ ] support for additional types — See #6
• [ ] support weak references — Some references are weak and thus when expanding them, they should be defined as T | null

GROQ Codegen:

• [ ] GROQ to TS transform — a new API to transform GROQ ASTs into TS ASTs
• [x] GROQ plucker/extractor (but buggy) — a new API to parse typescript or javascript files for GROQ queries
• [x] GROQ codegen API — a new API that ties the above two APIs

Client wrapper:

• [x] client wrapper — a wrapper for existing sanity clients (e.g. @sanity/client, picosanity) that augment their APIs for use with GROQ codegen

Jamstack client:

Note: This client is the successor to the current client. You may not need this package if you plan on using sanity-codegen with just the client wrapper

• [ ] Compatibility with the client wrapper
• [ ] Refined preview mode

CLI:

• [x] Refined CLI with help commands (via oclif)
• [x] New GROQ codegen command
• [ ] Watch modes

📅 Timelines

1. Get this version feature-complete (the items above)
2. Release a beta, focus on testing and iterating on the new APIs, gathering feedback
3. Release an RC, focus on documentation (and a docs site)

👋 Help Wanted

If you'd like to beta test the new version of this lib, please reach out to me at [email protected]. I'd love to get this new version in your hands and gather feedback. Right the docs for the new version aren't great so we'd need to connect to get you set up.

Warning the alpha is currently very rough!

[paul-vd]

API codegen docs — currently the API usage is relatively undocumented

To simplify the documents setup you can maybe opt for something like nextra, It is a really simple setup, and it supports md, mdx out of the box.

I tested it today for a new project, and had some documents setup in a matter of minutes.

[OllieJT]

Hey, how's it going @ricokahler ?

I was about to make a PR to improve types for SanityImage but didn't know the status of this release.

[ricokahler]

@OllieJT feel free to PR improvements to the current version!

this release is still in an alpha state and won't be production-ready until a month or so (though I am planning on releasing a beta in a few weeks)

[ricokahler]

I am planning on releasing a beta in a few weeks

So an update on this, I got overconfident on the previous approach and near the last 20%, it didn't pan out 😅.

TL;DR I'm rewriting the GROQ code generator from the ground up. See #149

[rix1]

Hi @ricokahler! Not sure if I've come to the right place, but I'm testing out the alpha release and I noticed that the asset metadata properties was fixed in https://github.com/ricokahler/sanity-codegen/pull/166 (thanks!). However, I don't think the the corresponding @sanity-codegen/types package was updated? Is that correct?

Is that depending on the rest of the 1.0 work, or would it be as simple as rebuilding and releasing the package? Not super familiar with TS, but let me know if I can help out in any way :v:

Btw, awesome project! 🙌

[rennehir]

Hi @ricokahler!

There has been almost a year since last commit. I'm pondering over using this library for my company and would like to know if you still have the intention to continue building this library?

[saiichihashimoto]

I think most of the work is going in the renovating, so I wouldn't look at main to see activity. Look like the last activity was end of November, which makes sense with holidays. I'd give this more time before deeming it stale. 😊

Another solution is sanity-typed-schema-builder, which uses a builder and derived types to accomplish the same thing that codegen is accomplishing here. Shameless plug. To be fair, I think with the new defineType in Sanity v3, there's a good chance that derived types might be able to accomplish all of this.

[mosesoak]

Hi @saiichihashimoto - thanks for the lead on a possible alternative! The lag on codegen supporting v3 has made us drag our heels on upgrading our projects.

To be fair, I think with the new defineType in Sanity v3, there's a good chance that derived types might be able to accomplish all of this.

Can you elaborate on this? What we want codegen for is not the studio itself, since V3 should have us covered there, it's copying the generated .d.ts file into the frontend apps that connect to sanity -- that is the true benefit of generating types.

[saiichihashimoto]

I was hoping I could use typescript itself to derive the document types from defineType to use in the apps themselves, to know the type of the docs. I don't remember which repo I commented on that with, but I tried to accomplish this and ultimately didn't see how it was possible. This project and sanity-typed-schema-builder seem to truly be the best (and honestly, only) way to get typescript types for your documents in your app itself. I prefer sanity-typed-schema-builder for a few reasons (I have lots of beef with codegen in most cases as a concept), but ultimately there's pros and cons to both approaches. The reality is that it would be best if sanity made all of this irrelevant by giving us a solid first-class solution to this, which is likely doable through stronger typing of defineType.

So:

• short term: use sanity-typed-schema-builder or this project.
• long term: find the dead ends from deriving document type out of defineType and make PRs against sanity to type it stronger to allow this.

[genox]

Yes this seems to be an issue of weighing pros and cons, more than anything. It's up to us to decide which compromise we are willing to take. The ideal solution would be to have sanity.io treat TS document typing on the receiving end as a first class issue that should be resolved.

With V3, I prefer to use the "sanity way" of defining schemas as I assume (or hope..) that sanity will have us covered there in the future, somehow.

For the time being, I can use the old version of sanity-codegen just fine with a few tweaks here and there, and it is much, much better than nothing. Or much better than using another completely different approach to generate schemas first in order to achieve typed documents, I would really prefer to stay away from this, to keep the studio parts as vanilla as possible. Maybe we should start a petition to request first class ts support from sanity directly. ;-)

Maybe the maintainer of this project knows more about the future of sanity's TS plans than we do, because it doesn't make sense to invest time in to a feature that will be dropped on us half a year later from sanity eventually. But also, maybe that's just my wishful thinking..