2022-03-09

Summary

Switching to @next/mdx approach was a mistake.
=> Return to next-mdx-remote OR a proper Content Layer API approach (which may include MDX processing e.g. https://contentlayer.dev does this)
My instinct right now is to go with https://contentlayer.dev since we will need functionality like allPosts
Implementation
- Leave data-literate for now - we backport the solution we find one we have it sorted
- Focus on next.datahub.io site: get an approach that works here
Next steps:
- Check out https://www.contentlayer.dev/
- Try out implementing to get blog system working
  - Remove current mdx approach
  - (?) Copy and paste from https://github.com/leerob/leerob.io
- Questions: do we use content layer to both provide our DB and render the MDX or do we separate the latter?

Notes

Switching to @next/mdx approach is wrong way to go.

Now that i reflect, i remember choosing next-mdx-remote for a reason which was precisely we can pull data from anywhere, supports frontmatter etc. Plus it's a cleaner model to generate the static paths explicitly in many ways.

See also https://dev.to/tylerlwsmith/quick-comparison-of-mdx-integration-strategies-with-next-js-1kcm which brings the cons of next/mdx home to me.

Re Content Layer API

#done/process to Content Layer API

Thoughts on a "content layer API".

Qu: how can I get a single or multiple "doc/page" so that I can render it or display it in some way

Let's get that more concrete:

https://excalidraw.com/#room=879858d5432d436072de,uXBslFeeknXaEXvgfyHNsQ

Research

https://twitter.com/rufuspollock/status/1500437127733170176

Options:

Tina: Nice, but tina seems to be doing too many things IMO and the key approach of static only (no server) is limited
ContentLayer: seems the KISS-est so far and good people behind it
Sanity: import data regularly (e.g. via https://github.com/kmelve/markdown-to-sanity) and then use Sanity API. 🔽 a real hack and painful to keep importing, not sure of markdown processing etc

Tina

Here you get a full graphql layer.

Content modelling: LINK TODO
- Can you do references (foreign keys): Yes
DB API: graphql
Simplicity: Medium
Can i use w/o server in SSG: sort-of 🚩

Notes

Here's a question i asked on their discord channel:

Hi, suppose i'm doing a pure static site. Can I use the tina graphql layer but call it from code in nextjs getStaticProps? Or do i have to run the server and then call the server …?

Put more explicitly is their a library endpoint to the graphql layer that i can use without running the server on port 4001?

The answer i found:

To answer myself: is the examples here what I'm looking for? https://github.com/tinacms/tinacms/discussions/2249 + https://github.com/tinacms/tinacms/blob/main/packages/%40tinacms/cli/GeneratedClientDocs.md

Answer from tina devs was:

This is a great question, and to add a bit of context the SDK does require for the GraphQL server to be running. But to answer your more broad question, you could do this without any http if your request is guaranteed to be statically executed at build time (getStaticProps and getStaticPaths). The reason we don't promote this pattern is that we'll soon be introducing the ability to make requests at runtime (and at that point, the filesystem often won't be there), so there would be a big difference in what's possible between getStaticProps and getServerSideProps logic, which we'd like to avoid.

So, in short - yes you can do this- but this isn't a stable API so beware this could change:
import {
  FilesystemStore,
  FilesystemBridge,
} from '@tinacms/datalayer'
import { resolve } from '@tinacms/graphql'

const bridge = new FilesystemBridge(rootPath)
const store = new FilesystemStore({rootPath})
const database = await createDatabase({ store, bridge })

const result = await resolve({
  database,
  query,
  variables,
})
You can see those in action:
https://github.com/tinacms/tinacms/blob/main/packages/%40tinacms/cli/src/cmds/start-server/index.ts#L67-L72

And here - https://github.com/tinacms/tinacms/blob/main/packages/%40tinacms/cli/src/cmds/start-server/server.ts#L54-L58

ContentLayer 👎

"Contentlayer": https://github.com/contentlayerdev/contentlayer (384 ⭐). "Turns your content into data - making it super easy to import MD(X) and CMS content in your app"

seems pretty good at first glance … but
very alpha with most of docs unfinished
one of founders of prisma seems to be behind it
somehow it doesn't feel quite right e.g. no query language, instead i get functions like allPosts
- That said … is that a big deal in a KISS solution
Here's the example of what leerob.io is doing https://github.com/leerob/leerob.io/blob/main/contentlayer.config.ts - quite simple and support for computed fields which is nice
Still have a bit of a "bad smell" instinct e.g. creating a mini database is separate from adding computed fields (?)

Key points

Restricted (i think) to one contentDirPath under which you have to all your different types of documents
You can then restrict document types based on glob patterns afaict
They are using kentcdodds mdx-loader under the hood - see https://github.com/contentlayerdev/contentlayer/blob/main/packages/@contentlayer/core/src/mdx.ts
How you then use the content: see example here https://github.com/leerob/leerob.io/blob/main/pages/blog/%5Bslug%5D.tsx

Asides

https://wundergraph.com/ - graphql api to your database (may be open source). 🔽 not that relevant IMO. More of a tool for a tool
- Instant Realtime APIs for any Database
- One unified GraphQL API for all your Data

Random

ContentLayer: release early and improve …

Random: example of quickly making a nice site: https://deploy-preview-31–contentlayer.netlify.app

See the rapid iteration from Alpha to Beta etc

Even in favicon: from simple red CL to nice(r) purple circle.

Also note how we start with just a stackblitz embedded screen showing how it works.