
Yesterday, I posted about [implementing i18n routing in a nextjs project](/garden/12-i18n-nextjs), focusing on the `app` folder and middleware setup. This post follows from that post with an `I18NLink` component that leverages our i18n set up to automatically prefix your links with the user's current language. This way, you can do something like this:

``` typescript
<I18NLink href="/settings">{t('settings', 'Settings')}</I18NLink>
```

And the link will automatically pick up the `lang` param to route to either `/settings` or (for example) `/es/settings` depending on the `lang` in the url.

Note: the `t` function is a stand in for a generic translation function that would take a key like `settings` and return a string or fallback to the second argument, which is "Settings".

## wrapping the `Link` component

The first thing we need to do is wrap NextJS's default `Link` component:

``` typescript
import type { ComponentProps } from 'react';
import React from 'react';
import Link from 'next/link';

export type I18NLinkType = Omit<ComponentProps<typeof Link>, 'as'> & {
  href: string;
};

function I18NLink({ children, href, ...props }: I18NLinkType) {
  return (
    <Link href={href} {...props}>
      {children}
    </Link>
  )
}
```

A few things are happening here:

1. We are creating a new `I18NLinkType` by taking the `Link` type and omitting `as` so we can use the component polymorphically.
2. We are defining `href` as a string since `Link` potentially accepts a `URL`.
3. We then create a function that's more or less a pass-through: take the `href` and `children` and just pass them to `Link`.

This isn't doing too much yet. We need to hook it into the `useParams` hook.

## get current `lang` param

Let's update the component:

``` typescript
import { useParams } from 'next/navigation';

// generic import of your default language
import { defaultLanguage } from 'settings';

function I18NLink({ children, href, ...props }: I18NLinkType) {
  const params = useParams();
  const currentLanguage = (params?.lang as string) || defaultLanguage;

  return (
    <Link href={`${currentLanguage}${href}`} {...props}>
      {children}
    </Link>
  )
}
```

Note that `params` could be `null` or an empty `Record`, so we want to coerce `lang` as a string.

This isn't a bad solution, but we're going to run into a few problems:

1. We don't want to prepend the `defaultLanguage` if we don't have to since it'll cause an extra redirect in the middleware.
2. We can't use the Link generically since it'll only work for relative paths. If we pass an absolute or external route, the url will be malformed.

## checking incoming href

What we need to do to prevent the above is check the incoming `href` and make decisions about what `href` to actually pass to `Link`.

``` typescript
function getPath(path?: string | null) {
  // 1.
  if (!path) {
    return ['en', ''];
  }

  // 2.
  const pathArray = path.split('/').filter((x) => !!x);

  // 3. empty array
  if (pathArray.length === 0) {
    return ['en', ''];
  }

  // 4.
  const [lang, ...restPath] = pathArray;

  // 5.
  if (languageArray.includes(lang)) {
    return [lang, restPath.join('/')];
  }

  // 6.
  return ['en', pathArray.join('/')];
}


function getPrefixedUrl(href: string, currentLanguage: string) {
  // 1. handle absolute links
  if (/^((http|https):\/\/)/.test(href)) {
    return href;
  }

  // 2.
  const [, tail] = getPath(href);

  // 3.
  if (currentLanguage === defaultLanguage) {
    return `/${tail}`;
  }

  // 4.
  return `/${currentLanguage}/${tail}`;
}
```

Let's start with `getPrefixedUrl`:

1. If the `href` starts with `http` or `https`, we should follow the absolute route provided.
2. Otherwise, we want to get the url path without the `lang` param if it's provided.
3. If the `currentLanguage` is also the default language, just pass the `tail` of the path
4. Otherwise, prepend the current language to the `tail` of the path

`getPath` might seem a little extraneous or verbose, but it's meant to help avoid issues with passing around the root and with overriding the `lang` provided in the url.

1. If the `path` is null, return an array we can use to route the user to the root of the site.
2. Take the path, and split it at `/`. The array is going to be easier to work with.
3. If the array is empty because `path === '/'`, return an array we can use to route the user to the root of the site. 
4. We want to deal with just `restPath` if (and only if) the first part of the url is actually an `lang` param.
5. We do a check to ensure that `lang` is include in our `langaugeArray`, which tells us we can safely use `restPath`
6. Otherwise we want to return the whole path we were provided

With these helper functions, we can update the component:

``` typescript
function I18NLink({ children, href, ...props }: I18NLinkType) {
  const params = useParams();
  const currentLanguage = (params?.lang as string) || defaultLanguage;
  const prefixedHref = getPrefixedUrl(href, currentLanguage);
  return (
    <Link href={prefixedHref} {...props}>
      {children}
    </Link>
  )
}
```

### bonus: anchor or `Link`

If you want to escape the client cache with a "hard" route, you might want to be able to use *either* an anchor or `Link` component:

``` typescript
export type I18NLinkType = Omit<ComponentProps<typeof Link>, 'as'> & {
  isAnchor?: boolean;
  href: string;
};

function I18NLink({ children, href, isAnchor, ...props }: I18NLinkType) {
  const params = useParams();
  const currentLanguage = (params?.lang as string) || defaultLanguage;
  const prefixedHref = getPrefixedUrl(href, currentLanguage);
  if (isAnchor) {
    return (
      <a href={prefixedHref} {...props}>
        {children}
      </a>
    );
  }

  return (
    <Link href={prefixedHref} {...props}>
      {children}
    </Link>
  )
}
```

We can just use a `boolean` and render an anchor tag based on `isAnchor` if passed.

## wrapping up

It would be great to have a more built in way to handle internationalization in NextJS, however it only requires a little bit of boilerplate to get a full fledged i18n setup, including automatic i18n routing with NextJS's default `Link` component.

Check out the full gist [here](https://gist.github.com/inadeqtfuturs/5281c16d825208fb36fec0ecb79d4d65).


i18n routing with nextjs 13 app router

automatic i18n linking with nextjs 13 app router


Recently at [graveflex](https://graveflex.com), I created a learning platform for one of our clients. In addition to mutli-tenant authentication and authorization, the whole platform needed to be translatable. Having done a handful of i18n sites in the past using [NextJS's pages router](https://nextjs.org/docs/pages/building-your-application/routing/internationalization), I was surprised to find how minimal the [app router] documentation was, largely leaving the complexity of routing to external packages.

Initially, I assumed that I could use one of these external packages to handle routing, but I ran into a few problems with each:

- [next-intl](https://next-intl-docs.vercel.app/docs/getting-started/app-router-server-components): needed more control inside middleware and didn't want to opt into what seemed like a fairly complex boilerplate set up they provide for `Auth.js`.
- [next-international](https://next-international.vercel.app/docs/app-setup): similar to `next-intl`, but we also didn't have the need to manage transations in the same way given our data structure and CMS.
- [next-i18n-router](https://github.com/i18nexus/next-i18n-router/): same concern about middleware, though, of all the solutions NextJS links out to, this one seems the like the most streamlined.

It seemed like it might just be easiest and that we could maintain the most control if we rolled out our own middleware. What we wanted was to define a set of potential locales (English and Spanish), and define one as the default locale. When the user was routing using the default locale, we didn't want the locale param to be displayed to the end user, however, the locale params *should* display when routing in any locale that is not the default.

``` javascript
`/` -> home
`/es` -> home translated
`/some-route` -> settings
`/es/settings` -> settings translated
```

The process of setting up the routing required two things: first, we need to wrap all routes inside the `app` folder in `[lang]` (or any dynamic route), and then set up the middleware to handle rewrites and redirects. The middleware needed to do the following:

1. check if there is a locale in the path
2. if there's no locale, we assume it's the default locale. however, *rewrite* the path to include the default locale so we have access to it from `useParams()`
3. if the locale is the default locale, redirect without the locale so the user doesn't see it in the url
4. if the locale is not valid, redirect the path with the default locale
5. otherwise, the locale is valid and the request should just pass through the middleware

While the above is opinionated, it defines, in general, how all of packages listed above work. Additionally, writing the middleware alerted us to handful of problems we might have run into otherwise.

## `app` set up

Following the conventions of i18n packages and NextJS's docs, we started by wrapping the entire file structure in the `app` folder in `[lang]`.

``` javascript
└── app/[lang]/
    ├── (public)
    │   ├── layout.tsx
    │   └── login/
    │       ├── LoginPage.tsx
    │       └── page.tsx
    └── (user)
        ├── layout.tsx
        ├── not-found.tsx
        ├── page.tsx
        ├── [...not-found]/
        │   └── page.tsx
        └── settings/
            ├── page.tsx
            └── layout.tsx
```

> Note: this is an overly simplified file structure to explain how the routing works.

There are a handful of things that happen when you set the routing up this way:

1. Because every route is nested under `[lang]`, you will always have access to the `lang` param either as a parameter in server components like `layout` or `page`, as well as `useParams`.
2. Defining [route groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups) as `(public)` and `(user)` allows us to separate the layouts, pages, and general data fetching we're doing for either authenticated or unauthenticated users.
3. Note the [catch-all segment](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#catch-all-segments) in the `(user)` folder -- this is a file that just returns `notFound()` so that we can (1) translate the not found page and (2) correctly display that page within the authenticated navigation shell.

## middleware set up

Knowing how we want the middleware to behave, we can break the function down into a few steps:

### set language config

First, we set up some constants to reference throughout the middleware.

``` javascript
const languages = ['en', 'es'];
const defaultLanguage = 'en'
```

### check for locale in path

``` javascript
import type { NextRequest } from 'next/server'

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const matches = pathname.match('^/([a-z]{2})(/.*)?$');
  const language = !matches ? 'en' : matches[1];
}
```

Inside the actual middleware function, we grab the `pathname` from the request and run it against a regex pattern that's looking for `/xx/` as the first part of the pathname. If you needed language and locale support, you could rewrite the regex to suit those needs. Otherwise, we set `langauge` to be either the default language, or the language passed in the path.

### handle no locale

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code

  // no locale -- assume en and rewrite so nextjs gets lang params
  // but user sees url without language
  if (!matches) {
    // note `newURL` 
    return NextResponse.rewrite(newURL(`/${defaultLanguage}${pathname}`, request));
  }
}
```

When there is no locale, we *rewrite* the request so that NextJS sees locale included in the URL, while the user does NOT see the locale in the URL.

Note the `newURL` function: we can't just pass the pathname because we're lose other parts of the url path. We knew we wanted to maintain (at the least) the query string params, so we wrote a function to pass those along:

``` javascript
// construct new url based on desired path and original request
function newURL(url: string, originalRequest: NextRequest) {
  const originalUrl = originalRequest.url;
  const query = originalRequest.nextUrl.searchParams.toString();

  const nextUrl = query ? `${url}?${query}` : url;

  return new URL(nextUrl, originalUrl);
}
```

### redirect if default locale is included

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code
  // redirect if defaultLanguage === language
  if (language === defaultLanguage) {
    return NextResponse.redirect(
      newURL(
        pathname.replace(`/${defaultLanguage}`, '/').replace('//', '/'),
        request
      )
    );
  }
}
```

If the `language` matches the `defaultLanguage`, we want to remove the language from the url so it can be handled by the rewrite.

### handle invalid language

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code
  const invalidLanguage = !languages.includes(languageFromPath);
  if (invalidLanguage) {
    return NextResponse.redirect(newURL(`/${defaultLanguage}${currPath}`, request));
  }

}
```

If the language we got from the path is not invluded in our languages array, route to the path but relative to the default language to either `200` throw a `404`.


### allow passthrough

If we have a valid language, we can just pass the request through.

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code
  return NextResponse.next();
}
```

### clean up

One thing you might notice is that we're not taking advantage of headers to pass the language around in requests. The main reason for this is simplicity and visibility: we don't want to obfuscate the user preferred language in a header when we can just have it as part of the URL.

However, we could (and should) leverage the browser's built-in language handling. To do this, we can wrap our responses in a helper function:

``` javascript
function addLanguageRespHeader(resp: NextResponse, lang: string = 'en') {
  resp.headers.set('Content-Language', lang);

  return resp;
}
```

Just pass along the `lang` as the second argument to set the header value:

``` javascript
  // ex.
  return addLanguageRespHeader(NextResponse.next(), languageFromPath);
```

## wrapping up

It might seem like a lot, but we can break the functionality of our middleware down to a few explicit steps and write the code ourselves. In the future, we'll probably package this along with instructions for composing it with other middleware.


garden monorepo


I recently started working on a new project and wanted to use NextJS across the stack. I thought it would be pretty straight forward to set up graphql api routes, but it ended up taking much longer to spin the project up than anticipated. I ended up abstracting the project architecture into a starter repo, which can be found [here](https://github.com/inadeqtfuturs/nextjs-sequelize-graphql-starter).

A brief overview:

- This is a full stack NextJS project that uses GraphQL api routes to interface with sequelize and a postgres database.
- The repo is diveded up into three sections: `database` for sequelize, `graphql` for the GraphQL schema and resolvers, and `src` for the frontend.
- Creating a new model is basically 2 steps: generate/define the model in sequelize, and then write the schema/resolvers in GraphQL.
- Because I was working on this while traveling (i.e. without internet access), it uses a project scope installed `sequelize-cli` and GraphQL Playground
- It frequently used sequelize commands aliased to `yarn`.
- The project can be deployed to Vercel or Netlify and hooked up to a Heroku hosted postgres (or whatever you prefer) database

The starter repo also comes with an example migration, model, and seed, as well as an example GraphQL schema and resolver with full CRUD operations.

If you're looking to quickly spin up a full stack NextJS project without configuring everything from scratch, this might be for you.


opinionated guide to internal documentation

next-mdx-relations

nextjs, graphql, sequelize starter


Much of my thinking over the last year or so has been about [digital gardening](https://maggieappleton.com/garden-history). I've written about [rethinking the digital gardening metaphor](/garden/03-rethinking-digital-gardening) and started building out [digital-garden.dev](https://digital-garden.dev) as a place to practice some of that thinking. In really broad strokes, I'm interested in the following:

1. Low friction authoring: write in markdown, but the system you use takes care of the rest
2. alternative/anti-hierarchical data arrangements: no pagination, but easily parsed lists of information
3. relational data: content is not the 'thing'. relations between things is the 'thing'

Some of this is idiosyncratic and theoretical, but a lot of it is practical. I want to develop tools that allow people to quickly and easily create digital gardens. [digital-garden.dev](https://digital-garden.dev) was supposed to be that tool, but I wanted to try developing a package rather than  boilerplate for gardening. [`next-mdx-relations`](https://github.com/inadeqtfuturs/next-mdx-relations) is a lower level tool for gardening that provides a more agnostic api for generating pages from `md/x` and drawing relations between those files.

### overview

If you want to spin up an `md/x` powered `nextjs` site, you nearly always are going to write some boilerplate. Either you're using [`next-mdx`](https://github.com/vercel/next.js/tree/canary/packages/next-mdx) and letting webpack sort things out, or, more likely, you're using some kind of `mdx` parser like [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote/) or [`mdx-bundler`](https://github.com/kentcdodds/mdx-bundler). In whatever case, you need to write functions for `getStaticProps` and `getStaticPaths` to generate paths and props for each page.

`next-mdx-remote` provides a really simple API that takes care of writing that boilerplate for you. Additionally, it allows for granular processing of `md/x` files and generating both extra metadata as well as relational data among static files in a collection.

### getting started

Install peer dependencies and package.[^1]

[^1]: I chose to keep these as peer dependencies in case you need functionality that `next-mdx-relations` doesn't offer. In that case, you have the raw material to glob, get the frontmatter, and serialize your markdown the way you like.

``` bash
yarn add fast-glob matter next-mdx-remote next-mdx-relations
```

Create a config file that imports `createUtils` from `next-mdx-relations` and both returns and exports functions for getting paths, pages, and pageProps.

``` js
// next-mdx-relations.config.js

import { createUtils } from 'next-mdx-relations';

export const {
  getPaths, // for `getStaticPaths`
  getPages, // for index page / `garden.js`
  getPageProps, // for `getStaticProps`
  getPathsByProp // for `[tag].js`
} = createUtils({
  content: '/content',
});
```

You get the following async helper functions

- `getPaths()`: use with `getStaticPaths` to get a list of file system based paths to your content
- `getPages()`: use in on your homepage to get a list of all your pages with accompanying frontmatter
- `getPageProps()`: use with `getStaticProps` to get your content and serialized frontmatter to pass to `next-mdx-remote`
- `getPathsByProp()`: use to make a tag page -- it returns a list of values of a given property from all of your content

If this pattern looks familiar, it's because it's heavily indebted to [stitches](https://stitches.dev/). I liked the idea of having the config file also be the place all of the package functionality is exported from. Additionally, this pattern allows you to have multiple instances of the package with their own scoped configurations. So if you have, like I did at one point, a blog and a garden, and those content types need to be handled differently, you can spin up two different configuration files (or put the `createUtils` function elsewhere) to handle either the blog or the garden.

Finally, create a `[...slug].js` file.

```js
// [...slug].js

import React from 'react';
import PropTypes from 'prop-types';
import { MDXRemote } from 'next-mdx-remote';
import { getPaths, getPageProps } from '../next-mdx-relations.config.js';

function Slug({ mdx, ...pageNode }) {
  const { frontmatter: { title, excerpt } } = pageNode;
  return (
    <article>
      <h1>{title}</h1>
      <p>{excerpt}</p>
      <MDXRemote {...mdx} />
    </article>
  );
}

export async function getStaticProps({ params: { slug } }) {
  const props = await getPageProps(slug);
  return {
    props
  };
}

export async function getStaticPaths() {
  const paths = await getPaths();
  return {
    paths,
    fallback: false
  };
}

export default Slug;
```

I've opted to use this catchall routing because it's the most generic way to handle routing. If you need something more granular, you can always make scoped catchall routes (ex. `/garden/[...slug].js`).

### meta and relational data

Relational data - the way things fit together, interact with each other, and (over)determine the meaning and value of other bits of data - seems to be the most important part of digital gardening. `next-mdx-relations` makes generating meta and relational data a first class feature by exposing two points of intervention when content is being processed.

``` js
const { getPageProps } = createUtils({
  content: '/content',
  // page level
  metaGenerators: {
    mentions: node => markdownLinkExtractor(node.content).filter(l => l[0] === '/')
  },
  // collection level
  relationGenerators: {
    mentionedIn: nodes => nodes.map((node) => ({
      ...node,
      meta: {
        ...node.meta,
        mentionedIn: nodes.filter(
          n => n.meta?.mentions.includes(`/${node.params.slug.join('/')}`))
      }
    }))
  }
})
```

In the above example, we use `metaGenerators` and `relationGenerators` to add extra meta and relational data to each page. `metaGenerators` work at the page or node level -- key value pairs have access to each `md/x` file in isolation. I'm using a package to return an array of links that point to local content. The return value is added to a node's `meta` object. `relationalGenerators` work at the collection level -- key value pairs have access to nodes after the `metaGenerators` have run. Unlike `metaGenerators` you can stash whatever the return value is anywhere on the nodes. Here, we see if any other node 'mentions' the current node, and add those nodes to the current's `meta` object. The result is a basic version of bi-directional links.

The above example is pretty straight forward, but achieves something slightly more difficult when working with static files alone. Additionally, `metaGenerators` can be used to generate data or mutate content outside of the markdown serialization.

### to follow

This is early days for the api. I'm still working out ways to keep things on the rails and not mutate data that shouldn't be, but I'm excited about what this has enabled me to build and what it might help others build, too.

Check it out on [github](https://github.com/inadeqtfuturs/next-mdx-relations).


site refresh


A lot has changed since I last worked actively on my blog/site. The previous iteration, which I released early in 2019, was built on technology I really liked at the time: [gatsby](https://www.gatsbyjs.com/) and [emotion](https://emotion.sh/docs/introduction). As time went on, really simple things became more and more difficult to do -- gatsby's data layer would break; plugins would need to be upgraded but would break the build process; the idiosyncratic theme I built in emotion became cumbersome and prevented me from actually making updates. In the interim, I had worked a lot with [nextjs](https://nextjs.org/) and really enjoyed the simplified data fetching I could do with `getStaticProps`. Having worked with `nextjs` to build [digital-garden.dev](https://digital-garden.dev), I decided to migrate *inadequate futures* over as well.

### overview

The major impetus for this update was to better showcase the work and writing I had been doing. The previous version of *if* was purposefully minimalist but that minimalism said less about what I was interested in working on and more about my design aesthetics. The homepage, just my name, job title, and a brief missive about what I do ('build elegant, responsive, and speedy software...') felt like an under- if not misrepresentation of my work and what I actually do. Additionally, many of the choices I made in the UX and design of the site ran against the grain of what I've learned to build and like. The work section, for example, was built out using a carousel, a design pattern I loathe both in terms of user experience and building, and showcased work that I haven't touched in years. In terms of writing, I had bifurcated my 'blog' from the 'garden', a demarcation that doesn't quite make sense to me from this vantage. Finally, the 'about' page was kept purposefully vague - something I thought I would update later but never did.

With this in mind, I wanted to make a few basic improvements:

1. a home page that more accurately describes/demonstrates my current interests and work
2. a single 'garden' section that can house all my writing. A list of posts is enough
3. a 'work' page that lists recent work and that is not a carousel
4. an about page that more accurately reflects my past/previous work and the role I see myself in going forward

With these things in mind, and with a basic design I made in figma in hand,[^1] I set off to do the heavy engineer lifting.

### gatsby → nextjs

I moved over to `nextjs` for a few reasons. First, it's what I've reached for both professionally and to build side projects for the last two years. The API feels very minimal and lightweight, it's fairly agnostic about how you load assets, and the build process is extremely fast. Second, I really like next's routing for generating static sites. I have a `[...slug].js` catch-all route for blog pages that exports a `getStaticPaths` and `getStaticProps` function. `getStaticPaths` returns an array of paths based on a folder with markdown files in it, and `getStaticProps` processes the markdown to render to the page. I can use the same `getStaticProps` functionality to get specific markdown files to generate specific pages, like the index or about page.

In broad stokes, I think `nextjs` provides one of the quickest ways to get a site built with React up and running.

### emotion → stitches

I've worked with both emotion and styled-components in the past, and I've built a theme generator and component library called [if-sf](https://github.com/inadeqtfuturs/if-sf), which is built on styled-components and [theme-ui](https://theme-ui.com/). While I really enjoy working with these technologies, I wanted to take the opportunity to try out some of the new styling systems that have emerged over the last two years. Having worked with [tailwind](https://tailwindcss.com/) on my [spotify dashboard](https://github.com/inadeqtfuturs/spotify-dashboard), I decided to try out [stitches](https://stitches.dev/) because it seemed lightweight, performant, and minimalist.

In addition to the `stitches.config.js` at the root of the project, which handles the theme object, I also wrote a `globalStyles.js` to define styles at the element level. Using `stitches`'s `global` function, it's easy enough to import these styles into my `_app.js`. While this works, I did miss how `theme-ui` took care of my mdx styles for me, and I hope this global element styling is something `stitches` can integrate into their existing api.

### next-mdx-relations

Having worked with `md/x` powered `nextjs` sites in the past, I had grown tired of writing boilerplate for getting file globs, parsing the markdown, and generating file paths to work with the catch-all `[...slug].js`. One of the goals in building [digital-garden.dev](https://digital-garden.dev) was to re-think the statically generated site in slightly more relational terms. Without a database, what and where is the best way and place to draw relations between these static files?

I wrote `next-mdx-relations` to try to answer this question. build on top of `next-mdx-remote`, another solution for parsing markdown for `nextjs` sites, `next-mdx-relations` provides two key things:

1. A set of utilities for generating paths and parsing markdown. No more boilerplate -- just give it the folder your content lives in and it handles the rest
2. An API that allows users to intervene at crucial points in the processing. Users can add extra metadata without writing to the markdown file, and has access to ALL files to generate relations between them

It's early days for `next-mdx-relations` -- I'm actively dogfooding it on this site -- but I'm already thinking that it's where I'll be working through some [questions I've asked](/garden/03-rethinking-digital-gardening) about digital gardening. I'd like for it to eventually power [digital-garden.dev](https://digital-garden.dev). In the mean time, you can check out the [github repo](https://github.com/inadeqtfuturs/next-mdx-relations).

### garden

I'm hoping this refresh returns me to the garden. I have some ideas for extending `next-mdx-relations` that would be useful for other digital gardens and I'm looking forward to working those things out.

[^1]: There is a longer and more interesting version of this post that talks through some of the design decisions, but I'm not a designer. Maybe for another time.


generating theme tokens

I'm currently building out a new digital garden over at [digital-garden.dev](https://digital-garden.dev) and writing about the process. The foundations are [next.js](https://nextjs.org/) and [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote), and I'm using them to generate static pages on build. This is a brief overview for working with dynamic routes and static generation in next.js.

### generating static pages

There are two important functions we use to generate static routes at build time with next.js. The first is `getStaticProps()`, which fetches data at build time and generates a page based on that data. The other is `getStaticPaths()`, which returns an array of paths that next.js will statically pre-render. While you can use `getStaticProps()` alone, it's helpful to see these working in tandem with one another. We generate a list of paths using `getStaticPaths` and pass that array to `getStaticProps`, which will process or fetch the data we need and generate the pages. We can also think about this in terms of file structure:

``` js
/posts
│   post-01.mdx
│   post-02.mdx
/pages
│   _app.js
│   _document.js
│   index.js
└───/posts
    │  [slug].js
```

In the file `/posts/[slug].js` (this path will become important later), we'll export `getStaticPaths`, pointing it at the `/posts` directory, getting a list of all the file paths we want to render. We'll additionally export `getStaticProps`, which will generate paths and pages for our mdx files at `/posts/post-01` and `/posts/post-02`. The `[slug].js` file can catch any mdx file in the `/posts` directory and generate a path and page for that mdx file. All the pages we generate will have a prefix of `/posts` because that's where the `[slug].js` file lives. We could similarly have `/notes/[slug].js` and generate pages with `/notes` as the path prefix.

### getStaticPaths // getStaticProps

Using our example repo, we can export a function called `getStaticProps` that looks like this:

``` js
import { promises as fs } from 'fs';
import path from 'path';
import glob from 'fast-glob';

...

const content = './posts';

export async function getStaticPaths() {
  // 1. define where the content is
  const contentGlob = `${source}/**/*.mdx`;
  // 2. get a list of files
  const files = glob.sync(contentGlob);
  // 3. if there are no files, return an empty array
  if (!files.length) return [];

  // see below
  const paths = await Promise.all(
    files.map(async filepath => {
      const slug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      return { params: { slug } };
    });
  );

  return {
    paths,
    fallback: false
  };
}
```

This function allows us to define where our content is and get a list of markdown files. We then map over the array of files, getting the file name without the extension (`path.extname(filepath)`) to use as our slug. However, because `getStaticProps` is expecting an array of objects that contain a `params` key, we need to return an array of objects rather than just a list of paths. `paths` ends up looking like this:

```js
paths = [
  { params: { slug: 'post-01' } },
  { params: { slug: 'post-02' } }
]
```

Now that we have the paths, we need to generate the pages. We'll export `getStaticProps`, which takes our paths as an argument:

``` js
import renderToString from 'next-mdx-remote/render-to-string';
import matter from 'gray-matter';

...

export async function getStaticProps({ params: { slug } }) {
  const contentGlob = `${source}/**/*.mdx`;
  const files = glob.sync(contentGlob);
  if (!files.length) return [];

  const posts = await Promise.all(
    files.map(async filepath => {
      const fileSlug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      // 1. read the file
      const mdxSource = await fs.readFile(filepath);
      // 2. use `matter()` to return the content and the frontmatter (data)
      const { content, data } = matter(mdxSource);
      // 3. render the mdx to string
      const mdx = await renderToString(content, {
        // we're not passing any custom components
        // see https://github.com/hashicorp/next-mdx-remote
        components: null,
        scope: data
      });

      return {
        slug: fileSlug,
        mdx,
        frontMatter: { ...data }
      }
    })
  );

  // make sure the path you hit actually has a post
  const [blogPost] = posts.filter(post => post.slug === slug);
  if (!blogPost) {
    // eslint-disable-next-line no-console
    console.warn(`No content found for slug ${slug}`);
  }

  return {
    props: {
      mdxSource: blogPost.mdx,
      frontMatter: blogPost.frontMatter
    }
  };
}
```

The first bits of code should look very similar. We're grabbing all of our content and generating slugs again. The difference here is we're also *reading* the file, getting both the frontmatter and the content of the post. The rest of the function just makes sure that when you hit a given path a post actually exists there. It returns what you'd need to render a post -- the source or content, and the frontmatter.

This is a really basic example of what you can do with static generation in next.js. But I also suspect a lot of folks will end up working with it to make static blogs, so hopefully this is helpful boilerplate.

### dynamic routes

In working on [garden](digital-garden.dev), I wanted to take dynamic routes a step further and allow for dynamic path prefixes based on where content lived. Let's return to the content directory example:

``` js
/content
└───/posts
    |   post-01.mdx
    |   post-02.mdx
└───/notes
    |   note-01.mdx
    |   note-02.mdx
```

Instead of a flat `/posts` directory, I now have a nested content directory. I want to be able to generate paths for my posts and notes based on their file path. A few ways you could do this.

1. In addition to `posts/[slug].js`, add an additional `notes/[slug].js` to catch the notes. The major downside here is just code repetition. It also requires adding a new directory to `/pages` every time there's a new kind of content.
2. Use a catch all route, so something like `[...slug].js` at the root of pages. This can end up being a bit mess as you get deeply nested routes (though it's something I'm thinking about now).

The solution I came up with is to have a catch all file at `/[path]/[slug].js` that generates paths that are one level deep (think the posts, notes, etc model) and keeps the slug logic intact. 

The first thing to do is update the `getStaticPaths()` function to return an array of objects with the shape `{ slugPath, slug }`. We'll also update `source` to be an array of strings that point to where our mdx files live.

```js
const contentSource = ['content/garden', 'content/note'];

export async function getStaticPaths() {
  const files = contentSource.reduce((acc, src) => {
    // using process.cwd() based on next.js documentation
    // https://nextjs.org/docs/basic-features/data-fetching#reading-files-use-processcwd
    const contentGlob = `${path.join(process.cwd(), src)}/**/*.mdx`;
    const files = glob.sync(contentGlob);
    return [...acc, ...files]
  }, [])

  if (!files.length) return [];

  const paths = await Promise.all(
    files.map(async filepath => {
      // get file name and use as slug
      const slug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      // get parent folder and use as slugPath
      const slugPath = path.dirname(filepath).replace(/^.*[\\\/]/, '');

      return { params: { path: slugPath, slug } };
    })
  )

  return {
    paths,
    fallback: false
  };
}
```

Using a reducer instead of a map, we end up with something like this:

```js
paths = [
  { params: { path: 'posts', slug: 'post-01' } },
  { params: { path: 'posts', slug: 'post-02' } },
  { params: { path: 'notes', slug: 'note-01' } },
  { params: { path: 'notes', slug: 'note-02' } }
]
```

This is not radically different than the initial example. Notice that we're just grabbing the parental directory name and passing that in as one of our params. Also notice that in the param object, we have two keys -- path and slug -- which correspond to our folder structure. `getStaticPaths` is going to expect these two keys to be in each `params` object, and we should update the `getStaticProps` to check for them:

``` js
export async function getStaticProps({ params: { path, slug } }) {
  ...
  const posts = await Promise.all(
    files.map(async filepath => {
      const slug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      // get parent folder and use as slugPath
      const slugPath = path.dirname(filepath).replace(/^.*[\\\/]/, '');

      ...

      return {
        slug: `/${slugPath}/${slug}`,
        mdx,
        frontMatter: { ...data }
      }
    })
  );

  // make sure the path you hit actually has a post
  const [blogPost] = posts.filter(post => post.slug === `/${slugPath}/${slug}`);
  if (!blogPost) {
    // eslint-disable-next-line no-console
    console.warn(`No content found for slug /${slugPath}/${slug}`);
  }
}
```

A small update, but we're making sure we get the correct content.

### wrapping up and future thinking

There's surely room for improvement here: a better way to handle slugs, perhaps a different way to catch routes (especially if we want deeper nested routes). However, if you need to spin up something quickly, this might be a good way for thinking about it.

### further reading

- [garden](https://github.com/inadeqtfuturs/garden)
- [mdnext](https://github.com/domitriusclark/mdnext/)
- [next.js](https://nextjs.org/)
- [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote)


building tag pages with nextjs

markdown, dynamic routes, next.js


High level overview for making index pages for each tag in your mdx/nextjs blog.

0. setup/assumptions

We'll use [`getStaticPaths` and `getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) to statically generate the tag pages. If a tag exists, we'll have a route like `site.com/tags/${tag}`. To do this, we'll set up a 'tag' folder with a `[slug].js` file in the pages folder.

I'm assuming that you already have tags in your frontmatter, and that you have some way of getting an array/list of all your posts. I highly recommend taking a look at [mdnext's utility file](https://github.com/domitriusclark/mdnext-blog/blob/master/src/utils/get-mdx-content.js) and this function in [next.js's blog example](https://github.com/vercel/next.js/blob/canary/examples/blog-starter/lib/api.js). Also worth taking a look at [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote#example-usage) both as an example and as because it's an excellent library for doing this.

1. get all posts

We need to get all our tags to generate a list of paths. We can do this in the `getStaticPaths` portion of the `[slug].js` file.

```js

export async function getStaticPaths() {
  const posts = await getAllPosts(directory);
}

```

2. accrete all tags

Next, we'll reduce those tags into a single array of strings.

```js
export async function getStaticPaths() {
  const posts = await getAllPosts(directory);
  const blogTags = posts.reduce((acc, { frontMatter: { tags } }) => {
    const newTags = tags.reduce((newAcc, tag) => {
      if (acc.includes(tag)) {
        return newAcc;
      }
      return [...newAcc, tag];
    }, []);
    return [...acc, ...newTags];
  }, []);
  const paths = blogTags.map(tag => ({
    params: {
      slug: tag
    }
  }));
}
```

Here, we're using a nested reducer -- for each array of tags in a post, we check if that tag exists in the accumulator for the `blogTags`. If it's already in there, like if another post already had that tag, we skip it, otherwise, we toss it into an array called `newTags` that we can spread into the `blogTags` acc. I like doing this rather than using a `forEach` and `push` because it's immutable.

3. use those tags to form pages

Now that we have an array of tags, we pass them as our paths parameter to the return value.

``` javascript
export async function getStaticPaths() {
  const posts = await getAllPosts(directory);
  const blogTags = posts.reduce((acc, { frontMatter: { tags } }) => {
    const newTags = tags.reduce((newAcc, tag) => {
      if (acc.includes(tag)) {
        return newAcc;
      }
      return [...newAcc, tag];
    }, []);
    return [...acc, ...newTags];
  }, []);
  const paths = blogTags.map(tag => ({
    params: {
      slug: tag
    }
  }));

  return {
    paths,
    fallback: false
  };
}
```

4. get posts associated with tag for each page

For each tag pages, we want to grab the associated blog posts. So we're grabbing all our posts and filtering to see which posts' tags include whatever the slug is.

```js
export async function getStaticProps({ params: { slug } }) {
  const posts = await getAllPosts(directory);
  const blogPosts = posts.filter(post => post.frontMatter.tags.includes(slug));

  if (!blogPosts) {
    console.warn(`No content found for tag ${slug}`);
  }

  return {
    props: {
      posts: blogPosts,
      tag: slug
    }
  };
}
```

We're returning the associated blog posts and the given tag. We can then doing something like this:

```js
export default function TagIndex({ posts, tag }) {
  return (
    <Layout>
      <h2>posts tagged {tag}</h2>
      {posts.map(post => (
        <Excerpt post={post} key={post.slug} />
      ))}
    </Layout>
  );
}
```


garden webpack plugin (or, bidirectional linking)


this post documents setting up the frontend portion of tangle.

This section covers the technical foundations including

- bootstrapping the lerna repo
- adding eslint and prettier
- setting up the frontend

### bootstrap lerna repo

``` bash
yarn init
yarn add lerna --dev
yarn lerna init
```

Add to package.json:

``` js
...
  'name': 'root',
  'private': true,
  'workspaces': [
    'packages/*'
  ]
...
```

Update lerna.json:

``` js
  'packages': ['packages/*'],
  'version': 'independent',
  'npmClient': 'yarn',
  'useWorkspaces': true
```

### gitignore

### eslint/prettier

Copy/paste eslint and prettier

``` bash
  yarn add babel-eslint eslint eslint-config-airbnb
  eslint-config-prettier eslint-plugin-import
  eslint-plugin-jsx-a11y eslint-plugin-prettier
  eslint-plugin-react prettier -W -D
```

`-W` for root flag

`-D` for dev dependencies

Add to package.json

``` js
    'lint': 'eslint --fix . && echo 'Lint complete.'',
```

Commit `[init]`.

## frontend / next.js

``` bash
  mkdir packages/web
  npx create-next-app packages/web
```

Select `Default starter app`

Update name of web app to `@tangle/web`

Add command to root package.json

```'web': 'lerna run --scope @tangle/web dev --stream'```

commit `[web] init`

We want to share react and next across the codebase. Add these as `devDependencies` to the root and add them as `peerDependencies` in whatever packages need them.

## component library

``` bash
  mkdir packages/components
  cd packages/components && yarn init -y
```

Name package `@tangle/components`.

Add peer dependencies

```js
  yarn workspace @tangle/components add -P react react-dom next
```

Add dependencies

```js
  yarn workspace @tangle/components add @emotion/styled @theme-ui/color styled-system theme-ui prop-types
```

Make a component

`packages/components/src/components/Button/Button.js`

``` js
  import React from 'react';
  import PropTypes from 'prop-types';
  import styled from '@emotion/styled';

  const StyledButton = styled.button`
    color: red;
    background-color: blue;
  `;

  function Button({ children }) {
    return <StyledButton>{children}</StyledButton>;
  }

  Button.propTypes = {
    /**
    * content of button
    */
    children: PropTypes.string
  };

  Button.defaultProps = {
    children: null
  };

  export default Button;

```

Add storybook

``` bash
  yarn add -W -D @storybook/react @storybook/addon-actions
  @storybook/addon-docs babel-loader @babel/core
```

Add `.storybook` directory w/ `config.js` and `main.js`

`config.js`

``` js
  import { configure, addDecorator } from '@storybook/react';

  addDecorator(storyFn => (storyFn()))

  configure(require.context('../packages/components/src', true, /\.stories\.js$/), module);
```

`main.js`

``` js
  module.exports = {
    stories: ['../packages/**/*.stories.js'],
    addons: ['@storybook/addon-docs']
  };
```

Add a story for the button

`Button.stories.js`

``` js
  import React from 'react';
  import { action } from '@storybook/addon-actions';
  import { storiesOf } from '@storybook/react';
  import Button from './Button';

  storiesOf('Button', module).add('default', () => (
    <Button onClick={action('clicked')}>test</Button>
  ));
```

update root `package.json`

``` js
  'stories': 'start-storybook'
```

Run storybook.

## clean up and code share

[babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver) helps us keep things looking clean.

``` bash
  yarn add -D -W babel-plugin-module-resolver eslint-plugin-import
  eslint-import-resolver-babel-module eslint-import-resolver-alias
```

add a `.babelrc` file

``` js
  {
    'plugins': [
      ['module-resolver', {
        'root': ['./'],
        'alias': {
          '@components': './packages/components/src',
          '@web': './packages/web'
        }
      }]
    ]
  }
```

add to `.eslintrc.js`

``` js
  settings: {
    'import/resolver': {
      'babel-module': {},
      alias: {
        map: [['@components', './packages/components/src']],
        extensions: ['.ts', '.js', '.jsx', '.json']
      }
    }
  }
```

add an `index.js` file to `components/src` and export the button component from there. Update the import in the `Button.stories.js` file to reflect the update

``` js
  import { Button } from '@components';
```

Run storybook to test.

Time to add the button to Next.js

Add a `babel.config.js` to the next app

``` js
  module.exports = {
    babelrcRoots: ['../packages/*'],
    presets: ['next/babel'],
    plugins: [
      [
        'module-resolver',
        {
          root: ['./'],
          alias: {
            '@components': '../components/src'
          }
        }
      ]
    ]
  };
```

We need to transpile the components as they come in:

`yarn workspaces @tangle/web next-transpile-modules`

Transpile components in the `next.config.js`

``` js
  const withTM = require('next-transpile-modules')([
    '../components/src'
  ]);

  module.exports = withTM();
```

Call the `Button` in your index to test. Run your next app.


styled system, variants, overrides

tangle

tangle frontend


This is the first in a series of posts documenting tangle, a fullstack monorepo that utilizes next.js and styled-system on the front end, with a graphql backend. The purpose of these posts is to, on the one hand, document the technical foundations of the repo and, on the other, act as an opening for thinking about the project more generally. Towards this end, I've split this post into two sections -- technical and theoretical.

### technical

tangle is an attempt to build a full stack monorepo boilerplate for quickly spinning up web apps. It's also an attempt to learn a bit more about full stack development -- I have a sense of how I want the codebase to work, but the solutions and integrations are not completely obvious from the outset. I do know that I want a few things:

- lerna monorepo to share code between projects
- shared tooling (eslint, prettier, jest, storybook)
- component library built on top of styled components and styled system
- web/front end built on next.js
- server/back end built on an apollo or express graphql server
- alternatively, serverless functions
- easy deployed to heroku/netlify/now

The directory structure is as follows:

``` bash
├── babel.config.js
├── lerna.json
├── package.json
├── packages
│   ├── api
│   ├── components
│   └── web
└── yarn.lock
```

Some of the motivating factors:

1. I find it easier to work in a codebase that's been bootstrap than bootstrapping the same project over and over. I want the ability to dive immediately into the code rather than fret over setup.
1. Because I'm pretty much only writing JS, shared tooling makes the most sense -- again: set and forget.
1. Splitting the frontend into a component library and web project allows the component library to grow organically (more in theoretical section) and isolates the dependencies the web project needs to deal with.
1. Additionally, splitting things up with way will eventually allow me to deploy just an api, or just a frontend app, or pull in just the component library.
1. Serverless functions are what I'd like to build into this, but there's some weirdness with where those functions should reside.
1. Someone else should be able to pick this up and deploy it eventually, so ideally it's easily deployed everywhere.

For MVP, I want to deploy the repo to Netlify, render a component from the component library, and display information by making a call to the server. This initial build (v 0.1.0) will also document the steps made to structure the codebase (i.e. an edited version of what I'll be doing here).

### theoretical

'Tangle' is a noun and a verb. To tangle is a process of becoming entangled; a tangle is the result. But tangles always seem to be tangling and untangling, retaining their tangliness in the process, until they become untangled, which is a wholesale different entity or status. In this way, a tangle is more than the sum of its parts or, at least, differs from the sum of its parts. We should also think about this in terms of entanglement, or the process through which not mutually exclusive objects or entities become somehow different in their interactions among one another (see Barad or Haraway on 'intra-activity'). A blunt and mundane example is the frontend's intra-action with a server or function or service -- they become different: an app, the exposure of data.

tangle, the project, takes these ideas as foundational in an anti-foundational way. I cannot know in advance what tangle will need or become, instead, I'm interested in allowing tangle to grow itself out as needed. Having a minimal, bootstrapped project allows for easy and speedy development that doesn't assume everything a developer would need. As something coalesces into a feature, it can become part of that boilerplate, or a more permanent part of the tangling. Yet, this is also an anti-foundational stance that refuses mastery -- of a set of practices or tool(ing)s -- in favor of humility and learning. tangle attempts to refuse assumption in an effort never to fully congeal. Instead, it'll just tangle on.

What I'm trying to outline here is a way of thinking about development and boilerplates less as full stop solutions to discrete problems than as process driven projects. In time, I want to think about what it would mean to take this stance further beyond the immediate realm of development (as coding or making a thing) into development as a set of relational practices among myriad people, technologies, and social forces.
