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.

🚧 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.

pnpm run dev

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.

The following arguments are listed in their order of operation.

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.

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.

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 },
  },
];

• 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 🥪

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

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' }];

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

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

Skips the specified number of entries. Accepts an integer.

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

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

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!

{
  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)
      },
    ]
  }
}

• 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

Accepts a function which takes in field names and transforms them for the GraphQL schema generation -- this is used internally to remove spaces but can be used for other global transforms as well

{
  ...
  // replace all spaces in field names with an underscore
  fieldNameTransform: (fieldName) => field.name.replace(/\s/g,'_')
  ...
}

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.

Clone the entire monorepo! Once you've installed dependencies with pnpm -w i, start a 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

Open another terminal tab.

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.

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 

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

pnpm build

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.