Flatbread 🥪

Eat your relational markdown data and query it, too, with GraphQL inside damn near any framework (statement awaiting peer-review).

If it runs ES Modules + Node 16+, it's down to clown.

Born out of a desire to Gridsome (or Gatsby) anything, this project harnesses a plugin architecture to be easily customizable to fit your use cases.

Install + Use

🚧 This project is currently experimental, and the API may change considerably before v1.0. Feel free to hop in and contribute some issues or PRs!

To use the most common setup for markdown files sourced from the filesystem, Flatbread interally ships with + exposes the source-filesystem + transformer-markdown plugins.

The following example takes you through the default flatbread setup.

pnpm i flatbread@latest

Automatically create a flatbread.config.js file:

npx flatbread init

If you're lookin for different use cases, take a peek through the various packages to see if any of those plugins fit your needs. You can find the relevant usage API contained therein.

Take this example where we have a content folder in our repo containing posts and author data:

content/
├─ posts/
│  ├─ example-post.md
│  ├─ funky-monkey-friday.md
├─ authors/
│  ├─ me.md
│  ├─ my-cat.md
...
flatbread.config.js
package.json

In reference to that structure, set up a flatbread.config.js in the root of your project:

import { defineConfig, transformerMarkdown, sourceFilesystem } from 'flatbread';

const transformerConfig = {
  markdown: {
    gfm: true,
    externalLinks: true,
  },
};
export default defineConfig({
  source: sourceFilesystem(),
  transformer: transformerMarkdown(transformerConfig),

  content: [
    {
      path: 'content/posts',
      collection: 'Post',
      refs: {
        authors: 'Author',
      },
    },
    {
      path: 'content/authors',
      collection: 'Author',
      refs: {
        friend: 'Author',
      },
    },
  ],
});

Now hit your package.json and put the keys in the truck:

// before
"scripts": {
  "dev": "svelte-kit dev",
  "build": "svelte-kit build",
},

// after becoming based and flatbread-pilled
"scripts": {
  "dev": "flatbread start -- svelte-kit dev",
  "build": "flatbread start -- svelte-kit build",
},

The Flatbread CLI will capture any script you add in after the -- and appropriately unite them to live in a land of fairies and wonder while they dance into the sunset as you query your brand spankin new GraphQL server however you'd like from within your app.

Run that shit 🏃‍♀️

pnpm run dev

Construct queries 👩‍🍳

If everything goes well, you'll see a pretty graphql endpoint echoed out to your console by Flatbread. If you open that link in your browser, Apollo Studio will open for you to explore the schema Flatbread generated. Apollo Studio has some nice auto-prediction and gives you helpers in the schema explorer for building your queries.

You can query that same endpoint in your app in any way you'd like. Flatbread doesn't care what framework you use.

NOTE: detecting changes to your content while Flatbread is running is not yet supported. You'll have to restart the process to get updated content.

Query arguments

The following arguments are listed in their order of operation.

filter

Each collection in the GraphQL schema can be passed a filter argument to constrain your results, sifting for only what you want. Any leaf field should be able to be used in a filter.

The syntax for filter is based on a subset of MongoDB's query syntax.

filter syntax

A filter is composed of a nested object with a shape that matches the path to the value you want to compare on every entry in the given collection. The deepest nested level that does not have a JSON object as its value will be used to build the comparison where the key is the comparison operation and value is the value to compare every entry against.

Example

filter = { postMeta: { rating: { gt: 80 } } };

entries = [
  { id: 1, title: 'My pretzel collection', postMeta: { rating: 97 } },
  { id: 2, title: 'Debugging the simulation', postMeta: { rating: 20 } },
  {
    id: 3,
    title: 'Liquid Proust is a great tea vendor btw',
    postMeta: { rating: 99 },
  },
  { id: 4, title: 'Sitting in a chair', postMeta: { rating: 74 } },
];

The above filter would return entries with a rating greater than 80:

result = [
  { id: 1, title: 'My pretzel collection', postMeta: { rating: 97 } },
  {
    id: 3,
    title: 'Liquid Proust is a great tea vendor btw',
    postMeta: { rating: 99 },
  },
];

Supported filter operations

• eq - equal
  • This is like filterValue === resultValue in JavaScript
• ne - not equal
  • This is like filterValue !== resultValue in JavaScript
• in
  • This is like filterValue.includes(resultValue) in JavaScript
  • Can only be passed an array of values which pass strict comparison
• nin
  • This is like !filterValue.includes(resultValue) in JavaScript
  • Can only be passed an array of values which pass strict comparison
• includes
  • This is like resultValue.includes(filterValue) in JavaScript
  • Can only be passed a single value which passes strict comparison
• excludes
  • This is like !resultValue.includes(filterValue) in JavaScript
  • Can only be passed a single value which passes strict comparison
• lt, lte, gt, gte
  • This is like <, <=, >, >= respectively
  • Can only be used with numbers, strings, and booleans
• exists
  • This is like filterValue ? resultValue != undefined : resultValue == undefined
  • Accepts true or false as a value to compare against (filterValue)
  • For checking against a property that could be both null or undefined
• strictlyExists
  • This is like filterValue ? resultValue !== undefined : resultValue === undefined
  • Accepts true or false as a value to compare against (filterValue)
  • Checking against a property for undefined
• regex
  • This is like new RegExp(filterValue).test(resultValue) in JavaScript
• wildcard
  • This is an abstraction on top of regex for loose string matching
  • Case insensitive
  • Uses matcher and matcher's API

Caveats:

• Currently cannot infer date strings and then compare Date types in filters
  • should work if you dynamically pass in a Date object from your client, though not extensively tested
  • if you wanna take a shot at that, start a PR for adding arg typeOf checks and subsequent unique comparator functions 🥪

Combining multiple filters

You can union multiple filters together by adding peer objects within your filter object to point to multiple paths.

Example

Using the entries from the previous example, let's combine multiple filters.

query FilteredPosts {
  allPosts(
    filter: { title: { wildcard: "*tion" }, postMeta: { rating: { gt: 80 } } }
  ) {
    title
  }
}

Results in:

result = [{ title: 'My pretzel collection' }];

sortBy

Sorts by the given field. Accepts a root-level field name. Defaults to not sortin' at all.

order

The direction of sorting. Accepts ASC or DESC. Defaults to ASC.

skip

Skips the specified number of entries. Accepts an integer.

limit

Limits the number of returned entries to the specified amount. Accepts an integer.

Query within your app ❓❓

Check out the example integrations of using Flatbread with frameworks like SvelteKit and Next.js.

Field overrides

Field overrides allow you to define custom GraphQL types or resolvers on top of fields in your content. For example, you could optimize images, encapsulate an endpoint, and more!

Example

{
  content: {
    ...
    overrides: [
      {
        // using the field name
        field: 'name'
        // the resulting type is string
        // this can be a custom gql type
        type: 'String',
        // capitalize the name
        resolve: name => capitalize(name)
      },
    ]
  }
}

Supported syntax for field

• basic nested objects

  nested.object

• a basic array (will map array values)

  an.array[]

• a nested object inside an array (will also map array)

  an.array[]with.object

for more information in Overrides, they adhere to the GraphQLFieldConfig outlined here https://graphql-compose.github.io/docs/basics/what-is-resolver.html

☀️ Contributing

You're encouraged to join our Slack and ask questions! Let us know if anything is unclear - if so, that just means we need to improve our docs 😁 We can help set you off on the right foot so you don't feel like you're flying blind.

init

Clone the entire monorepo! Once you've installed dependencies with pnpm -w i, start a development server:

development server 🎒

This will run a dev server across packages in the monorepo

You may need to seed this with a pnpm build first, as there can be a race condition with parallel type generation. After that, you can automatically & incrementally build changes with:

pnpm dev

working on a package ⚒️

Open another terminal tab.

☝️ Keep the dev server running in your other tab

Option 1: use the SvelteKit example as a demo project

This allows you to work in the full context of a Flatbread instance as an end-user would, except you can tinker with the packages internals.

pnpm play

This is a good option when you want to test without creating temporary clutter per-package that you wouldn't want to commit.

Option 2: scope to a specific package

In the new tab, scope yourself into the specific package you wanna mess with.

cd packages/<package>

Run the file containing where you invoke your function at the top level.

node dist/index.mjs # ya need Node v16+

build for production 📦

This will use tsup to build each package linked in the monorepo except the integration examples.

pnpm build

📓 Sidenotes

Huge shoutouts to @antfu and @sveltejs/kit for both having invaluable reference points to guide me through learning more advanced Node, Typescript, and monorepo design all in parallel during this project.