DEV Community: Anthony Gushu

Flatbread 🥪 - consume relational, flat-file data using GraphQL in any static framework

Anthony Gushu — Fri, 01 Jul 2022 19:28:56 +0000

TLDR; I built a framework-agnostic tool that gives you the markdown/YAML file -> GraphQL server experience of Gridsome/Gatsby.

Problem

Storing your relational data as files in a git repo, deployed onto a static site target (Netlify, Vercel, etc.) can be an incredibly powerful pattern with the only running cost being the price of the domain name.

I love using NetlifyCMS for generating that data as markdown files, then querying it from a compile-time GraphQL API into a static site. However, I found that when you go this direction, you're typically pigeonholed into using Gatsby, Gridsome, or Hugo - unless you have very simple, non-relational data. This has the consequence of dictating many aspects of your code and effectively vendor-locks you into the strong opinions of those frameworks.

Those frameworks are great and tons of work has gone into them, but I wanted total freedom to use something like SvelteKit, Remix, or Astro while having the same flat file -> local GraphQL server experience.

So as it goes, I built something to scratch my own itch...

Enter, Flatbread

I'm using it for a little tea log that's currently in the process of migrating from Gridsome to SvelteKit + Flatbread. Hopefully others find this useful! 😄

Installation

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, markdownTransformer, filesystem } from 'flatbread';

const transformerConfig = {
  markdown: {
    gfm: true,
    externalLinks: true,
  },
};
export default defineConfig({
  source: filesystem(),
  transformer: markdownTransformer(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.

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

For more details, please check out the docs in the Github repo: https://github.com/tonyketcham/flatbread

🔖 Sidenotes

This is very much in Alpha and there are a couple quirks that need ironing out.

Handling cross-collection, mongoDB-style filtering.
- That type of filtering is currently supported when done within a single collection, such as fetching a single post with a matching slug or title field, or all posts with a publish date greater than or equal to a week ago.
- This library is ESM-centric, and while it also exports a CJS bundle, I haven't yet tested strongly in environments outside of Vite or Svelte(Kit). So while the plan is to test integration with all sorts of frameworks, all I can currently promise is that it's framework-agnostic by design and should work with all sorts of static-enabled things like Astro, Remix, Next, Nuxt, etc.

I'd love to find more people to work on Flatbread with me as I'm coming up against some interesting challenge areas and feel there's tons of potential here to disrupt this niche of the ecosystem

🐝 Sapper Template w/ Tailwind 2.0, TypeScript, ESLint, and Prettier 🍯

Anthony Gushu — Mon, 15 Feb 2021 06:34:18 +0000

I faced the conundrum of starting a new Sapper project with Tailwind 2.0, ESLint, Prettier, and the whole shebang.

Unfortunately for me, all the templates I came across were outdated or a bit too verbose/hacky.

Fortunately for you, I turned my research into a new and improved Sapper template featuring all the nuts and bolts of a more advanced config to help you hit the ground running!

Sapper-Tailwind2-Template repo

🔑 Usage

You can jump in with a quick

npx degit "tonyketcham/sapper-tailwind2-template" my-winded-app
cd my-winded-app
yarn install
yarn dev

Static Stuff 🗞

This also has shortcuts for working with SSG.

yarn static

This will export your site into static files and open a local production server on localhost:5000. You can run this to make sure everything matches your dev server and that you didn't mess up the one Tailwind caveat I'm about to touch on.

🚪 Closing arguments

There are too many dead Sapper templates so the obvious answer is to just add one more to the sea, right? 🥶

If you've got any input or PRs, feel more than welcome to drop them on the repo to keep this thing running for when the ecosystem inevitably gets updated in the future. I'd also love to keep this alive as a SvelteKit template when that finally drops too.

p5-Svelte: a quick and easy way to use p5 in Svelte! 🕸🧙‍♂️

Anthony Gushu — Sat, 16 Jan 2021 06:40:15 +0000

Have you ever tried to throw p5 into a Svelte project? It's kinda a pain in the ass!

So guess what - I've done n made a component for the Svelte and p5 privy or intrigued to savor your sweet, generative teeth on.

Behold, p5-svelte

🛴 Usage

Giving it the good ol' ball of yarn:

yarn add p5-svelte

<script>
  import P5 from 'p5-svelte'
</script>

<P5/>

Run that and you should see the sketch we're about to make below 🚣‍♀️

Full Example 🗿

Let's implement the 10print algorithm (in the cover photo) using p5-svelte:

<script>
  import P5 from 'p5-svelte';

  /**
  * a peeFive'd 10print algorithm
  * @see {@link https://10print.org/} to learn about it!
  * @param {p5} p5 instance mode
  */
  const sketch = (p5) => {
    let x = 0;
    let y = 0;
    let size = 15;
    let threshold = 0;

    p5.setup = () => {
      p5.createCanvas(400, 400);
    };

    p5.draw = () => {
      p5.stroke(1);
      threshold = p5.random(0.75);

      if (threshold < 0.1) p5.line(x, y, x + size, y + size);
      else if (0.505 > threshold > 0.5) p5.line(x, y, x, y + size);
      else p5.line(x, y + size, x + size, y);

      x = x + size;
      if (x > p5.width) {
        x = 0;
        y = y + size;
      }
    };
  };
</script>

<P5 {sketch} />

Doing npm run dev, we're left with this beaut (give the gif a second to load if it's not showing up immediately):

Use Svelte's Reactivity ♻️

This is my favorite aspect of this component. You can use all the shiny Svelte features to make reactive UIs bound to aspects of your p5 sketches with great DX. Maybe make an interactive web editor or some weird utility with powerful and intriguing UI interactions??

Here's a simple example of two Svelte inputs bound to the width and height of an ellipse in p5:

<script>
  import P5 from 'p5-svelte';
  let width = 55;
  let height = 55;

  const sketch = (p5) => {
    p5.setup = () => {
      p5.createCanvas(400, 400);
    };

    p5.draw = () => {
      p5.ellipse(p5.width / 2, p5.height / 2, width, height);
    };
  };
</script>

<label>
  Width
  <input type="range" bind:value={width} min="100" max="1000" step="0.01" />
  {width}
</label>
<label>
  Height
  <input type="range" bind:value={height} min="100" max="1000" step="0.01" />
  {height}
</label>

<P5 {sketch} />

p5.js instance mode

You perhaps noticed it in the example, but Svelte doesn't allow us to globally expose the p5 library by installing it to the window (which is how p5 is commonly installed in vanilla js projects). Therefore, p5 must be used in instance mode with this component.

Contributing

I would love some pull requests if anyone finds some areas of improvement and would like to contribute!
Go at it: p5-svelte repo on GitHub

Fun fact, this component was made using Svelte Actions.

Is Gridsome scalable?

Anthony Gushu — Wed, 09 Dec 2020 05:01:52 +0000

I've been testing the waters with Gridsome for some smaller statically-generated eCommerce & blog projects with great success. There, the amount of content, frequency of publishing, and desired timeliness of content going live aren't too intense. So in those projects, build times aren't an issue.

Though something I've been toying with is the idea of bringing my day job's news publishing platform (which uses good ol' WordPress, jQuery, and PHP) into a more modern Vue-centric frontend stack that's either SSR'd or statically generated. I'm interested in what a headless Gridsome frontend might look like at scale for our publishing platform.

We've got about 100k pieces of content with related & recent posts that'll populate on each page as cache invalidation happens on a publishing event. The current response time from publishing to a live audience article is somewhere in the 5s-30s range.

As I've developed my smaller Gridsome projects, I do see the build times increasing. However, I haven't been able to get a feel for how the quantity of content relates to consecutive build times where one to three pieces of content are added or updated every hour.

Something I wonder about Gridsome is how efficiently the build cache works at a scale of tens or hundreds of thousands of pages. Obviously, it wouldn't be ideal for a news org if the whole platform has to be rebuilt for 30 minutes each time a piece of content is updated.

This very well could be something I just prototype to gather info on my own and get a feel for real-world scenarios and scalability. I can't seem to find any info online about how Gridsome handles this kind of scale and if there are any issues that boil up besides build-time complexity potentially becoming a deal-breaker.

Any insight from the wiser of us who have been around the block would be wonderfully appreciated

Anecdote

Just to give some rationale to why I'm considering going SSG on top of Vue, the pain points of being locked into a custom WP theme have created quite a bit of technical debt and we're looking to become more agile with more powerful frontend capabilities, better page speeds, and better SEO scores.

Vue + Tailwind 2.0: dark mode using Vuex, localStorage, and user's default preference

Anthony Gushu — Sun, 22 Nov 2020 14:31:47 +0000

TailwindCSS 2.0 is sick. Native dark mode, tons of colors, tons of other shit. I just so happened to start a new Gridsome project for documenting my recently developed tea dependency right when Tailwind 2.0 dropped, and I wanted to toss in some theme toggling to represent the dark times ahead.

The kind of conditional theming I want is a little complex:

first-time visitors should be displayed their OS/browser preferred theme
the user's theme choice should be respected throughout their session
the user's theme choice should be saved in local storage so that they don't have to battle the UI when they return

While Tailwind has an option to pop theme selection into manual mode, the example in the docs for driving stick is vague and purposely non-specific. CTRL+C CTRL+V won't do a ton for us here, so we're on our own in VS Code.

Let's implement our own stateful dark mode solution using Vuex and localStorage.

The deep state

After dicking around trying to add Vuex into an existing Gridsome project for 45 minutes while the official Gridsome docs decided to take me out back to the console.error firing squad, I eventually got to the point of being the proud father to my very own Vuex store:

import Vue from 'vue'
import Vuex from 'vuex'
import theme from './modules/theme'

Vue.use(Vuex)

export default new Vuex.Store({
    state: {},
    mutations: {},
    actions: {},
    modules: {
        theme
    },
})

Now inside that theme.js module, we can do some simple tricks to tuck most of our logic away from the frontend. Let's start with the state and mutation:

export default {
    state: {
        theme: {}
    },
    mutations: {
        SET_THEME(state, theme) {
            state.theme = theme;
            localStorage.theme = theme;
        }
    },
...

We're keeping the mutation incredibly simple so that its sole responsibility is updating the theme's state. Saving that to localStorage allows us to retrieve the user's most recently selected theme after closing the page and coming back later, essentially like a cookie.

Now think about what happens when a first-time user pops on our site. There's a chance they've selected either the light or dark theme on their OS or browser, which we can and should respect. Notice that we haven't initialized the theme state with anything yet. That's going to be our first action:

...
 actions: {
        initTheme({ commit }) {

            const cachedTheme = localStorage.theme ? localStorage.theme : false;
            //  `true` if the user has set theme to `dark` on browser/OS
            const userPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

            if (cachedTheme)
                commit('SET_THEME', cachedTheme)
            else if (userPrefersDark)
                commit('SET_THEME', 'dark')
            else
                commit('SET_THEME', 'light')

        },
...

This action will then see if the user has been to the site before:

If so, we use their cached theme preference.
If the person is new, we check to see if their system is set to dark mode. If so, we commit our store & cache to dark mode.
Else, we default to light mode.

We can dispatch this action from an omnipresent root of the app that everyone will hit no matter their point of entry:

// for me this is `layouts/Default.vue`, but for you it may be `App.vue` or something else
export default {
  beforeMount() {
    this.$store.dispatch("initTheme");
  },
...

Now we need a switch to toggle the theme.

Before making that component, let's go back to theme.js to add in the logic:

...
// This simply flips whatever was most recently committed to storage.
    toggleTheme({ commit }) {

            switch (localStorage.theme) {
                case 'light':
                    commit('SET_THEME', 'dark')
                    break;

                default:
                    commit('SET_THEME', 'light')
                    break;
            }
        }
    },
    getters: {
        getTheme: (state) => {
            return state.theme;
        }
    },
}

Tailwind 2.0's `dark` class

From here, we can add in some properties to conditionally render on dark mode. Then we'll set up a watcher that will react to changes to the theme selection by running a function that adds and removes Tailwind's dark css class to the root node of our app:

<template>
  <main
    class="min-h-screen 
           bg-green-50 text-gray-700 
           dark:bg-gray-900 dark:text-purple-50">
    <ThemeToggler/>
    <slot />
  </main>
</template>

<script>
import { mapGetters } from "vuex";
import ThemeToggler from "../components/ThemeToggler.vue";

export default {
  components: {
    ThemeToggler,
  },
  beforeMount() {
    this.$store.dispatch("initTheme");
  },
  computed: {
    ...mapGetters({ theme: "getTheme" }),
  },
  watch: {
    theme(newTheme, oldTheme) {
      newTheme === "light"
        ? document.querySelector("html").classList.remove("dark")
        : document.querySelector("html").classList.add("dark");
    },
  },
};
</script>

And the last piece, our incredibly underwhelming toggler:

<template>
    <button 
     @click="toggleTheme"
     class="dark:text-red-400 text-cyan-200">
      Theme Toggle
    </button>
</template>

<script>
export default {
  methods: {
    toggleTheme() {
      this.$store.dispatch("toggleTheme");
    },
  },
};
</script>

Creative freedom

This is lovely because you can get wild, replace the text with some SVGs, and add transitions out the wazoo to translate between states. You can use Vue's built-in transition elements or Tailwind's transition classes, or both!

If you have any questions, suggestions, or more elegant solutions, please post them below! I spotted a couple of areas that could be more elegant, like using Vue's conditional classes instead of vanilla-ing the dark class on and off the root element.

How to: embed a Svelte app within a PHP application, with Live Reload

Anthony Gushu — Fri, 26 Jun 2020 18:52:32 +0000

Woah it's my first DEV article!

Alright, so at my day job I inherited a system built on PHP. The DOM is almost completely rendered in PHP which annoys the hell out of me -- I've been dreaming sweet thoughts of Svelte.

Wanting to make the switch, I often thought about redoing the whole system using fetch() requests in Svelte with a request-response scheme in PHP, but there's so much code that a Big Bang-style switch isn't feasible. Therefore, I needed to plant a seed that would eventually grow into something large and beautiful (perhaps a tea tree, or a napa cabbage).

So this morning I decided fuck it, it's time to put Svelte's clean little hands on some PHP-rendered DOM. And spoiler: it's pretty painless.

Slap in Svelte

You've first got to choose a sub-project to use Svelte on within your existing PHP project.

Navigate to that directory of your existing project in the terminal and drop in our old friend:



 > npx degit sveltejs/template svelte
 > cd svelte
 > npm install

Here's what my project directory looks like:

Now let's tie 'em together! Pop into index.php, and add a point of entry. I chose:



<div id="svelte-app"></div>

On the Svelte end, match this entry point as your target in main.js:



import App from './App.svelte';

const app = new App({
  target: document.getElementById('svelte-app'),
  props: {
    name: 'world',
  },
});

export default app;

Now we essentially have to recreate the core parts of
svelte/public/index.html.

We're going to link the Svelte-generated script and stylesheets. This part can be done two ways depending on your existing PHP project. If you have direct access to the html head, then just copy and paste the link and script elements from the head of index.html to the PHP file's head, with path adjustments to reach the same files they reference.

In my case, I don't have a direct access method to augment scripts/stylesheets to the head in this PHP project. While I could make a method for that, I kinda just felt like doing it in Javascript. So I added this into the PHP file:



<script>
    const svelte_script = document.createElement('script');
    svelte_script.type = 'text/javascript';
    svelte_script.defer = true;
    svelte_script.src = '../svelte/public/build/bundle.js';
    document.head.appendChild(svelte_script);

    const svelte_global_stylesheet = document.createElement('link');
    svelte_global_stylesheet.rel = 'stylesheet';
    svelte_global_stylesheet.href = '../svelte/public/global.css';
    document.head.appendChild(svelte_global_stylesheet);

    const svelte_compiled_stylesheet = document.createElement('link');
    svelte_compiled_stylesheet.rel = 'stylesheet';
    svelte_compiled_stylesheet.href = '../svelte/public/build/bundle.css';
    document.head.appendChild(svelte_compiled_stylesheet);
</script>

Do whichever floats your pontoon, until someone argues below that the Javascript way is perhaps less efficient and makes us all feel bad for doing something that feels cool.

Now this will work if you do npm run build from the svelte folder with MAMP or whatever Apache server you have running for the PHP part, but dammit we want live-reload and automation!

Live Reload

This is the perfect point to add live-reload to your PHP server if you haven't already. If you're using VSCode, add Live Server and its browser extension.

Configure the browser extension with the virtual host name set in, say, MAMP as the actual server address. Then the server that this plugin runs, usually http://127.0.0.1:5500/:

Follow the plugin's guide, hit Go Live in index.php and you should be PHP-live-reloading. But maybe wait to test this until after the next step so to avoid some Node server-Apache server fighting if you've got Svelte's localhost running too.

We only need Rollup in Svelte to be responsible for watching Svelte file changes and compiling those changes. To make this happen, we can delete the following lines from the rollup.config.js:



// In dev mode, call `npm run start` once
// the bundle has been generated
!production && serve(),

Now, with your terminal still in the svelte directory, you can run the familiar



> npm run dev

Now Rollup will notice changes to your Svelte files, and auto-recompile like normal. Live Server will then notice a change to the compiled Svelte files referenced in your PHP application and reload your PHP page in the browser automatically!

You can get rid of favicon.png and index.html from the Svelte public folder, too.

Look at that!

There's a whole number of ways to pass data between your PHP backend and Svelte interface, so I might turn this into a series the more I dive into the possibilities!