
I'm working on a theme/token generating library based on [theme-ui](https://theme-ui.com/) and [emotion](https://emotion.sh/docs/introduction). I've found myself using some variation of the same theme object across projects, but as I iterate on that object either improving it or tweaking it, I find it increasingly difficult to keep different versions up to parity. An example: I update how I'm using breakpoints in one so I need to go through each project and update the breakpoints there.

One solution would be to publish the theme object as an npm package, but I wanted something a little more dynamic. [speculative fabulation (or sf)](https://github.com/inadeqtfuturs/if-sf) generates theme tokens (ex. colors, typography, buttons) as well as theme objects (ex. an object comprised of theme tokens). These can be passed into `emotion`'s or `styled-components`'s theme provider. `sf` operates on the idea that objects go in, objects come out -- you can extend, merge, or override theme defaults, allowing granular control over the theme you generate:

``` js
const defaultTheme = genTheme();
const defaultThemeWithNewColor = genTheme({ colors: { newColor: '#333' } });
```

Both functions return a full theme object, but you can drill down and update the specific tokens you need.

### token generators

`genTheme()` is broken down into a series of token generators -- functions that return a token object, like colors or styles for a button. In working on these token generators, I set up a few parameters for how they should behave:

0. generator files export a token object
1. generators return a token object
2. generators don't require arguments to return the token object
3. generators merge and extend the token object by default
4. generators can wholesale override the token object

For something like colors, this is simple enough:

``` js
import { merge } from 'theme-ui';

const defaultColors = {
  text: '#111827',
  background: '#F9FAFB',
  primary: '#2563EB',
  secondary: '#DE7283',
  accent: '#7C3AED',
  muted: '#88d1FF'
};

export function genColors({ override, ...restColors } = {}) {
  if (override) {
    return override;
  }
  if (!restColors) {
    return defaultColors;
  }
  return merge(defaultColors, restColors);
}

export default defaultColors;
```

By default, `genColors()` returns `defaultColors`. If we pass an `override` argument, it will return that object instead. Any other key/value pair we pass gets merged into default colors.

### token generators -- deep and defaults

Things became slightly more complicated as I began working with typography. In the past, I've defined a default text base that includes things like font size, line height, and font family, spreading that object into each typographical element (i.e. p, ul, blockquote, etc.) (I'm ultimately leveraging the `theme.styles` object from [theme-ui](https://theme-ui.com/styling-mdx)). This works for the first two generator requirements -- have a base set of styles; spread them into each element, return that:

``` js
export const defaultTextBase = {
  fontFamily: 'body',
  fontSize: ['sm', 'md'],
  lineHeight: 1.5,
  margin: 0,
  padding: 0,
  marginBottom: 4
};

const defaultText = {
  p: {
    ...defaultTextBase
  },
  ul: {
    ...defaultTextBase,
    paddingLeft: 8,
    ul: {
      margin: 0
    }
  },
  ...
}
```

The problem starts when I want to extend or merge styles into the base: if we're just spreading `defaultTextBase` into these elements, at what point do we actually merge or extend the base? One way to solve this would be to iterate through the keys in `defaultText`, spreading the base as we went, but this would prevent us from exporting an object from the generator file. Another way to handle this would be to get a diff between the new base and default base -- after all, we're just extending or merging into it. However, this presents an immediate problem if we're going to wholesale override the base at some point. So I ended up writing a utility that removes the default values (if present) from each element.

``` js
function removeDefaults(obj, defaultObj) {
  const defaultKeys = Object.keys(defaultObj);

  // mapObject does what it sounds like: allows us to map the key/value pairs in an object
  // mapObject = (obj, func) => Object.fromEntries(Object.entries(obj).map(func));
  return mapObject(obj, ([key, value]) => {
    const remainingValues = Object.keys(value).reduce((acc, curr) => {
      if (defaultKeys.includes(curr) && defaultObj[curr] === value[curr]) {
        return { ...acc };
      }
      return { [curr]: value[curr], ...acc };
    }, {});
    return [
      key,
      {
        ...remainingValues
      }
    ];
  });
}
```

Once the default values are removed, we can determine the new base (overriding, merging into, or extending the default base) and use the above `mapObject` function to pass that base into each key. You can see the full implementation [here](https://github.com/inadeqtfuturs/if-sf/blob/main/src/theme/tokens/text/index.js)

### spread defaults // remove defaults

Something about this pattern seems useful, though I'm not entirely sure where. It goes something like this:

1. Have a default base
2. Spread that default base into each key of a token object. Export that object.
3. If you need to extend or override that base, use the above function to remove those defaults
4. Return new object using new base

I like this pattern, though I think it fits a specific use case. I do think it could be used in a more generalized way, and I'd be interested to hear alternative approaches to the above problem.


site refresh

markdown, dynamic routes, next.js

generating theme tokens


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.
