
# Babel Macros

[Babel](https://babeljs.io/) macros are a way to apply code transformations
without having to install a new plugin for each transformation. They are
implemented in a clever way and can be very useful. And best of all, they work
out of the box with Create React App, GatsbyJS, and NextJS. This post will dive
into what they are, how to use them, and how to make them using TypeScript.

## Why?

Regular Babel plugins are great, but come with a few downsides.

- They can be difficult for users to setup and configure, especially when using
tools like [CRA](https://create-react-app.dev/) and
[Gatsby](https://www.gatsbyjs.org/). CRA [straight up prevents you](https://github.com/facebook/create-react-app/issues/167) from
editing the config.
- Plugins can lead to confusion as it can be unclear what in the code is being
transpiled and what isn't.
- They can conflict in non-intuitive ways. The ordering you define the plugins
  in is important and when the ordering causes a bug, it can be impossible to
  debug.
  
Babel macros to the rescue!

## What?

Babel macros are possible because of the
[babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) library
(which is itself a Babel plugin).

This library enables other libraries to create macros by

1. treating all imports that end in `.macro` or `/macro` as a macro.
2. providing a `createMacro` function that gives access to Babel.

## But TypeScript?

If you use TypeScript you can still benefit from the power of macros. Instead of
using the TypeScript compiler (tsc) to compile your code, you can use Babel
with the [TypeScript preset](https://babeljs.io/docs/en/babel-preset-typescript)
instead. This is what CRA, Gatsby, and Next are already configured to do.

## Usage

If you are not using CRA, Gatsby, or Next and have full control over the Babel
pipeline, you can enable using Babel macros in your project by adding the
dependency (if you are using these tools, then you don't have to install or
configure anything).

```shell
npm i --save-dev babel-plugin-macros
```

and adding it to your Babel config

```json
// .babelrc
{
  "plugins": ["macros"]
}
```

Use a macro just by importing it like any other JavaScript dependency. For
example, the [count.macro](https://github.com/coffee-cup/count.macro).

```javascript
import { lines } from "count.macro";

console.log(`This file has ${lines} lines`);
```

## Development

Let's make a macro! The macro will place the contents of a file into a variable
at compile time. A user will be able to use it like this:

```ts
import file from "my.macro";

const contents = file("my-file.txt");
```

This section assumes you have some knowledge of
[ASTs](https://en.wikipedia.org/wiki/Abstract_syntax_tree) and how to manipulate
them with Babel. The [plugin
handbook](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md)
and [AST explorer](https://astexplorer.net/) are great resources for learning or
familiarising yourself with these concepts.

### Caveats

There are a few caveats you have to keep in mind when developing a macro.

- Macros are evaluated at compile time. This means that the code you write must
  be able to run in Node on whatever machine is using the macro. This means no
`import/export` syntax... unless you compile your macro before using it
(_meta_). In this example we will use TypeScript and compile with `tsc`, but you
can just as easily write your macro in ES6 and compile it with Babel. Just
remember, after updating your macro, **remember to recompile**.
- They must be synchronous. If you do in file IO, make sure to use the sync version.
- To enable type checking when the macro is used in TypeScript, you must lie
  about the type.

### TypeScript

We are going to develop it in TypeScript. If you are not using TypeScript you
can still follow along, just remove the type definitions.

### Setup

First we need to install our dependencies. We will use `yarn` for this.

```shell
yarn add babel-plugin-macros
yarn add --dev typescript jest ts-jest @types/babel__core @types/node @babel/cli @babel/preset-typescript
```

If using TypeScript, create a tsconfig file. [Something like
this](https://github.com/coffee-cup/count.macro/blob/master/tsconfig.json).
Also, if you are using TypeScript you will want to add some definitions for
`babel-plugin-macros` (the ones on
[DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) are a bit
outdated at the time of writing this. There is a PR open to update them). You
can [grab the updated ones from here](https://github.com/coffee-cup/count.macro/blob/master/typings/babel-plugin-macros.d.ts).


Next we can add some npm/yarn scripts.

```json
"scripts": {
  "build": "tsc -p .",
  "test": "jest",
  "compile": "yarn run build && babel --plugins=babel-plugin-macros --presets=@babel/preset-typescript"
}
```

The `compile` script will first compile our macro, then compile an example file
with Babel. This is really helpful when testing and developing.

Finally, we can create our macro and an example to test with.

```ts
// src/index.macro.ts

// TODO
```

```ts
// examples/test.ts
const x = 1;
```

Run our example with

```shell
yarn compile examples/test.ts
```

You should see the contents of the file output to the console. Awesome! We are
now setup.

### Macro Definition

A macro is created by calling the `createMacro` function from
`babel-plugin-macros`. The macro must be the default export.

```ts
import { createMacro } from "babel-plugin-macros";

const myMacro = createMacro(/* ... */);
export default myMacro;
```

The first argument to `createMacro` is a function that takes an single
parameter: an object with a references, state, and Babel field. This is the type
definition:

```ts
export type References = {
  [key: string]: Babel.NodePath[];
};

export interface MacroParams {
  references: { default: References } & References;
  state: any;
  babel: typeof Babel;
}

export type MacroHandler = (params: MacroParams) => void;

export function createMacro(handler: MacroHandler, options?: Options);
```

#### references

This is the main thing our macro will use to manipulate the AST. References is
an object that contains Babel `NodePaths` for all the places your macro was
imported. For example, if I have the following source.

```ts
import foo, { bar } from "my.macro";

foo(); // line 3
foo(); // line 4

const x = bar + 1; // line 6
```

References will be:

```ts
{
  default: [/* NodePath line 3 */, /* NodePath line 4 */],
  bar: [/* NodePath line 6 */]
}
```

This is important to note and tripped me up when I was first learning about
macros. 

> The default export of your macro file is always called with references
to all places it was imported and used. Even if the user imports a named
export from your macro, the default export will still be called.

Since references contain Babel `NodePaths`, they allow use to manipulate the
ASTs. This is what we will use below.

#### state

The state of the file being traverse. This is the second argument received in a
visitor function of a normal Babel plugin. It will look something like:

```json
{
  "file": {
    "declarations": {},
    "path": NodePath,
    "ast": Node,
    "code": string,
    "opts": {
      /* ... */
    },
    "scope": Scope
    // ...
  },
  "filename": string
  // ...
}
```

#### babel

Same as `require("babel-core")`. We can use it to get [Babel
types](https://babeljs.io/docs/en/babel-types).

```ts

const myMacro = ({ references, state, babel }) => {
  const t = babel.types;
};
```

## Our Macro 

With the above knowledge, here is our macro.

```ts
import { createMacro, MacroHandler } from "babel-plugin-macros";
import * as fs from "fs";
import * as path from "path";

const myMacro: MacroHandler = ({ references, state, babel }) => {
  const t = babel.types;
  const currentFilename = state.file.opts.filename;

  references.default.map(({ parentPath }) => {
    if (
      t.isCallExpression(parentPath.node) &&
      t.isStringLiteral(parentPath.node.arguments[0])
    ) {
      const filename = path.resolve(
        path.dirname(currentFilename),
        parentPath.node.arguments[0].value
      );
      const contents = fs.readFileSync(filename, "utf8");
      parentPath.replaceWith(t.stringLiteral(contents));
    }
  });
};

export default createMacro(myMacro) as (filename: string) => string;
```

You can see I had to manually case the type to `(filename: string) => string`.
This way TypeScript users will get type checking and autocomplete when using
this macro. If my macro was a named export instead, I could type with:

```ts
export const file = null as (filename: string) => string;
```

Finally, we can change the example to:

```ts
// examples/test.ts
import file from "../lib/index.macro";

const contents = file("test.ts");
```

The tranpsiled code will be,

```ts
const contents = "import file from \"../lib/index.macro\";\n\nconst contents = file(\"test.ts\");\n";
```

## Conclusion

Babel macros are a great way to add compile time transformations to your
project. They are low effort to setup and already work if you are using CRA,
Gatsby, or Next. There are already a lot of macros available (check out
[awesome-babel-macros](https://github.com/jgierer12/awesome-babel-macros)), but
I believe there is still a lot of untapped potential. They are also fairly easy to
create, especially if you already have some experience writing Babel plugins.


tags: [[web]]

Babel Macros

babel-macros


# CSS

Design language of the web

tags: [[web]]


# Cursors

I often forget all the options for cursors in [[CSS]] and testing each one in Chrome is tedious and time consuming. That is why I made Cursors. Available at [cursors.jakerunzer.com](https://cursors.jakerunzer.com). A small [[web|website]] that shows you all examples of CSS cursors and allows you to copy them to clipboard.

![Screenshot of Cursors](https://user-images.githubusercontent.com/3044853/115191624-8a453380-a09e-11eb-82da-bd7534f59197.png)

Source is [available on GitHub](https://github.com/coffee-cup/cursors).

This also the first thing I've built using [SvelteKit](https://kit.svelte.dev/). It has been a great experience so far and I expect I will use [[Svelte]] a lot more in the future for tiny sites like this.





Cursors

cursors


# Custom Property Themes

project based on [[theming-with-custom-properties]]

Library that takes a list theme and returns
- a transformed theme that refers to CSS variables
- CSS to add to the page that create the custom variables

It can also take a bunch of themes keyed by color mode and create the css for that.

```ts
const themes = {
  light: {
    fg: "black",
	bg: "white"
  },
  dark; {
  	fg: "white",
	bg: "black"
  }
}

const defaultColorMode = "dark";
const {transformedThemes, css} convertThemes(defaultColorMode, themes);

transformedThemes
// =>
{
  light: {
    fg: "var(--fg)",
	bg: "var(--bg)"
  },
  dark; {
  	fg: "var(--fg)",
	bg: "var(--bg)"
  }
}

css
// =>
:root {
  --fg: "white";
  --bg: "black";
}

[data-theme="dark"]: {
  --fg: "white";
  --bg: "black";
}

[data-theme="light"]: {
  --fg: "black";
  --bg: "white";
}
```

tags: [[web]]

custom-property-themes


# Introducing Favocon

Favocon is a small command line utility I made for generating favicons from
images. It is available on [cargo](https://crates.io/crates/favocon), the
[[Rust]] package registry.

![favocon usage gif](https://user-images.githubusercontent.com/3044853/57985881-5dc5ae80-7a66-11e9-8a8a-fff327b83e73.gif)

[Favicons](https://en.wikipedia.org/wiki/Favicon) are the little icon you see on
the tab for a website.

Favicon files (`.ico` extension) contain one or more small icons inside of them.
When they were invented they were useful because the same file could be used for
a websites icon in the browser and a websites icon when saved to the desktop
(something a lot more popular in 1999). Browsers today look for `<link
rel="icon" href="...">` tags in the HTML and support multiple file formats and
sizes. However, they still fallback to a `favicon.ico` placed at the root of the
website.

Generating these files can be a pain. I would normally have a single high
quality icon I want to use, and somehow need to generate PNGs at multiple
resolutions, an ICO file, and a [site manifest
file](https://developers.google.com/web/fundamentals/web-app-manifest). I would
often just Google "favicon generator" and use one of the top results, which
don't get me wrong, work really well. But I wanted something with less friction.

Favocon does just that. In its simplest usage just call `favocon` with a path to
an image file. All the files you need will be saved to `favocon/` and The HTML you
should place in the head of your `index.html` file are output to the console.

The tool is [free to use](https://crates.io/crates/favocon) and [open source on
Github](https://github.com/coffee-cup/favocon). Please feel free to contribute
or create an issue if you think of any improvements.

tags: [[web]]

Intorducing Favocon

favocon


# GitHub Apps and OAuth

2 Primary ways to access GitHub content of a user

- GitHub app
- OAuth app

[Difference between them](https://docs.github.com/en/free-pro-team@latest/developers/apps/differences-between-github-apps-and-oauth-apps)

> An OAuth App acts as a GitHub user, whereas a GitHub App uses its own identity when installed on an organization or on repositories within an organization.

e.g. Vercel commenting on PR with link to preview -> GitHub app

----

Apps have access to repos defined in an _installation_, which is scoped to a specific user/organization.

You can find your app at https://github.com/apps/your-app. Here, a user can install the app or configure installations of it.

You can jump to installation configuration at 
https://github.com/apps/your-app/installations/new

which shows a screen like

![[Pasted image 20201212111457.png]]

---

Typical flow

1. Login with GitHub button
    - User goes through OAuth flow and can see your app in the "Authorized OAuth Apps" section in GH settings
1. Create installation for scope
    - User is redirected (typically displayed in popup) to github.com/apps/your-app/installations/new where they can configure what repos the app has access to
1. Show list of repos in your UI and let user select
    - Fetch all repos that your installations for the user have access to (personal account, any orgs they have added installation to)
    
 ---
    
# Creating Repos    

For an installation to create GitHub repo you need administration write permissions

You can create a repo as an OAuth app, but then to listen to webhooks and stuff on it later, you need to be an installation.

tags: [[web]]


Developing Github Apps

github-apps


# Learning Resources

- [ThreeJS Journey](https://threejs-journey.com/) tags: [[web]] [[3d]]
- [Crafting Interprets](https://craftinginterpreters.com/contents.html) tags: [[languages]]
- [Black Hat Rust](https://academy.kerkour.com/black-hat-rust) tags: [[Rust]]
- [Rust in Action](https://www.rustinaction.com/) tags: [[Rust]]
- [PNGme](https://picklenerd.github.io/pngme_book/) tags: [[Rust]]
- [Nifty Assignments](http://nifty.stanford.edu/) tags: [[languages]]

Learning Resources

learning resources


# Merging User Accounts

Services that allow you to login with multiple providers (e.g. Google, Facebook, Twitter) will also, sometimes, let you merge accounts. This is important if the user forgets which provider they had previously used to create an account with.

User can create an account with their email or via various social logins (e.g. Login with GitHub). The user is logged out and the next time they go to login they forget which service they previously used. They proceed to use a different service. How does the system respond?

Options are
1. Merge the accounts based on some unique identifier
2. Create another account for the user

Sometimes services allow users, once signed in, to sign in with another platform and then the accounts will be linked that way. This isn't as ideal as the user must do this once already logged in.

The solution provided here is decent, https://stackoverflow.com/a/6906457/1345618

1. User logs in via a third party identity
2. Once logged in they have the option to connect other third party logins
3. If they forget and login with another once, the system creates another user account for them. 
4. From there they can connect the original third party login. The system will detect the collision and offer to merge the accounts

tags: [[web]]

Merging User Accounts

merging-user-accounts


# Notion as a CMS

[Notion](https://www.notion.so/) is a great authoring tool, especially for teams. It allows you to organize content in pages as well as supports structured data in the form of [databases](https://www.notion.so/Intro-to-databases-fd8cd2d212f74c50954c11086d85997e).

Using Notion as a CMS is a great option for teams that want a low effort [blog](https://blog.railway.app) or [changelog](https://railway.app/changelog).

## How

[This repo](https://github.com/ijjk/notion-blog) is a great example of how render data from a private notion page with NextJS. The data is fetched at build time and refetched in the background using [SSG](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation). This example has basically reversed engineered the notion api since there is no official API available, [yet](https://www.notion.so/api-beta?utm_source=social&utm_medium=twitter&utm_campaign=api_private_beta).

[This blog](https://splitbee.io/blog/notion-as-cms-using-nextjs) post explains how to use NextJS and [react-notion](https://github.com/splitbee/react-notion) to render public notion pages. They also use [notion-api-worker](https://github.com/splitbee/notion-api-worker) to cache API responses. Although this isn't as important if the data is fetched in the background with SSG.

tags: [[web]]

Notion as a CMS

notion-as-cms


# React Charting Libraries

Comparison of various charting libraries for the [[web]] (focused on [[React]]).

## visx

[github.com/airbnb/visx](https://github.com/airbnb/visx)

> Collection of expressive, low-level visualization primitives for React

- Based on D3
- Modular (small size)
- Low level. Allows you to create your own chart library on top of it
- No animation built in. But there are examples using react-move and react-spring

## Recharts

[recharts.org](http://recharts.org)

> Composable charting library build on React components

- Built on SVG and D3
- Fairly well used
- A lot of possible customization

## Frappe

[frappe.io/charts](https://frappe.io/charts)

> GitHub-inspired simple and modern SVG charts for the web with zero dependencies

- Simple
- Not declarative or React based

## Victory

[formidable.com/open-source/victory/](https://formidable.com/open-source/victory/)

> React.js components for modular charting and data visualization

- Robust
- Flexible
- Decent guides

## nivo

[nivo.rocks](https://nivo.rocks/)

> Rich set of dataviz components, built on top of d3 and React

- D3 and React based
- Supports server side rendering
- Animation built in
- Less customization and more plug and play

React Charting Libraries

react charting libraries


# TypeScript in the Browser

![Stock image of a laptop and code](https://images.unsplash.com/photo-1545670723-196ed0954986?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1952&q=80)

I recently had to get [[Typescript]] running in
the browser an online code editor that
gives you live feedback on your code. We had previously only showed parse and
runtime errors, but we wanted to show more advanced type errors that are only
detectable with static analysis (e.g. TypeScript).

TypeScript can easily be used programmatically for files on the file system.
With a little configuration it can even be run on code that only exists in
memory. However, running TypeScript in the browser with no access to the file
system turned out to be a bit more challenging than I thought. In this post I
will go over setting up a TypeScript language service that you can use to get
type errors, quick info, documentation, etc, of code in the browser.

All code in this post can be found in [this
CodeSandbox](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il).

Credit where credit is due: [Andrew's](https://twitter.com/atcb) blog post,
[_Overengineering a blog_](https://blog.andrewbran.ch/overengineering-a-blog/),
and [associated source](https://github.com/andrewbranch/blog) were an invaluable
resource. Thanks Andrew!

---

The main functionality I wanted was to query the compiler for type errors.

```ts
function typecheck(code: string): TypeError[] {
  /* ... */
}
```

For this I reached for the TypeScript language service, which is a layer on top
of the core compiler and provides common editor like operations.

![TypeScript language service](https://raw.githubusercontent.com/wiki/Microsoft/TypeScript/images/architecture.png)

To typecheck code in the browser we need the following:

- Virtual system
- Compiler host
- Language service host
- Language service
- Type files for any language features we want to use

## System

A `ts.System` contains methods for reading files, writing files, checking if a
file exists, etc. If you run TypeScript in Node, then the system is a wrapper
around `fs`. The filesystem does not exist in the browser, so we have to create
our own _virtual_ system. The full file is [here](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il?file=/src/system.ts).

```ts
// system.ts
import * as ts from "typescript";

export function createSystem(files: { [name: string]: string }): ts.System {
  files = { ...files };
  return {
    // ...
    directoryExists: directory =>
      Object.keys(files).some(path => path.startsWith(directory)),
    fileExists: fileName => files[fileName] != null,
    getCurrentDirectory: () => "/",
    readFile: fileName => files[fileName],
  };
}
```

We pass in an object from filename → file contents that contains all of our
files on our virtual filesystem.

## Library Types

TypeScript knows the types of variables and functions through the use of
declaration files (`.d.ts` extension). These are what you download when you
install a package from DefinitelyTyped (`@types/package`).

Since there are many different versions of TypeScript/JavaScript, the types of
core language features are not baked into the compiler. Declaration files for
the languages features you want to use must be included in the virtual file
system. This is what the `lib` field in your `tsconfig.json` file configures.

In this demo we will use es2015 and dom features, equivalent to

```json
// tsconfig.json
{
  // ...
  "lib": ["es2015", "dom"]
}
```

The decalaration files are in `node_modules` and can be loaded at build time using the Webpack `raw-loader`.

```ts
// tsLib.ts
export const libs = {
  "/dom.d.ts": require("!raw-loader!typescript/lib/lib.dom.d.ts"),
  "/es2015.d.ts": require("!raw-loader!typescript/lib/lib.es2015.d.ts"),
  "/lib.es5.d.ts": require("!raw-loader!typescript/lib/lib.es5.d.ts"),
  "/lib.es2015.d.ts": require("!raw-loader!typescript/lib/lib.es2015.d.ts"),
  "/lib.es2015.core.d.ts": require("!raw-loader!typescript/lib/lib.es2015.core.d.ts"),
  "/lib.es2015.collection.d.ts": require("!raw-loader!typescript/lib/lib.es2015.collection.d.ts"),
  "/lib.es2015.generator.d.ts": require("!raw-loader!typescript/lib/lib.es2015.generator.d.ts"),
  "/lib.es2015.promise.d.ts": require("!raw-loader!typescript/lib/lib.es2015.promise.d.ts"),
  "/lib.es2015.iterable.d.ts": require("!raw-loader!typescript/lib/lib.es2015.iterable.d.ts"),
  "/lib.es2015.proxy.d.ts": require("!raw-loader!typescript/lib/lib.es2015.proxy.d.ts"),
  "/lib.es2015.reflect.d.ts": require("!raw-loader!typescript/lib/lib.es2015.reflect.d.ts"),
  "/lib.es2015.symbol.d.ts": require("!raw-loader!typescript/lib/lib.es2015.symbol.d.ts"),
  "/lib.es2015.symbol.wellknown.d.ts": require("!raw-loader!typescript/lib/lib.es2015.symbol.wellknown.d.ts"),
};
```

If we wanted to use a third party library, we could include the type file here.

## Compiler Host

The TypeScript compiler interacts with the host environment via a compiler host.

```ts
const compilerHost: ts.CompilerHost = {
  // ...
  getCanonicalFileName: fileName => fileName,
  getDefaultLibFileName: () => "/lib.es2015.d.ts",
  getDirectories: () => [],
  getNewLine: () => sys.newLine,
  getSourceFile: filename => sourceFiles[filename],
  useCaseSensitiveFileNames: () => sys.useCaseSensitiveFileNames,
};
```

The compiler host uses `ts.SourceFile`s for representing files on the
filesystem. These include the content of the file as well as additional
metadata, such as the language version. We can easily create source files from
an object from filename -> contents.

```ts
const sourceFiles: { [name: string]: ts.SourceFile } = {};
for (const name of Object.keys(files)) {
  sourceFiles[name] = ts.createSourceFile(
    name,
    files[name],
    compilerOptions.target || ts.ScriptTarget.Latest,
  );
}
```

## Language Service Host

The language service host "abstracts all interactions between the language service and the external world. The language service host defers managing, monitoring, and maintaining input files to the host" ([source](https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API#language-service-host)).

This means that the only way the compiler can access the outside world is through the language service host.

```ts
const languageServiceHost: ts.LanguageServiceHost = {
  // ...
  getCompilationSettings: () => compilerOptions,
  getScriptFileNames: () => Object.keys(files),
  getScriptSnapshot: filename => {
    const contents = sys.readFile(filename);
    if (contents) {
      return ts.ScriptSnapshot.fromString(contents);
    }

    return undefined;
  },
};
```

In the above code we create a `ScriptSnapshot` instead of returning the contents of the file as a string because they allow efficient incremental parsing. The snapshot contains information about the entire contents of the file, as well as changes made from a previous snapshot. Since we are not worrying about incremental parsing in this demo, a new snapshot is created every time.

## Language Service

The final thing we need is a `ts.LanguageService`. This will be our main
interface into the compiler. In a proper application you would create the
language service once and update the (virtual) file contents as you need. This
would allow the compiler to perform various optimizations such as only
parsing and typechecking code that has changed. However, in our demo we will
create a new language service every time we want to typecheck some code.

```ts
const languageService = ts.createLanguageService(languageServiceHost);
```

## Getting Diagnostics

The language service contains a bunch of useful functions for querying the compiler.

![language service available functions](./language-service.png)

The one we are most interested in is `getSemanticDiagnostics`, which will return an array of `ts.Diagnostic`s that look like,

```ts
{
  file: SourceFileObject;
  start: number;
  length: number;
  code: number;
  messageText: string;
}
```

The field `messageText` is a human readable description of the problem found.

## Implementation

Using the information above, lets implement a function for typechecking some input code.

First, we need to specify some compiler options. This object looks nearly
identical to what you find in `tsconfig.json`.

```ts
const compilerOptions: ts.CompilerOptions = {
  ...ts.getDefaultCompilerOptions(),
  jsx: ts.JsxEmit.React,
  strict: false,
  target: ts.ScriptTarget.Latest,
  esModuleInterop: true,
  module: ts.ModuleKind.None,
  suppressOutputPathCheck: true,
  skipLibCheck: true,
  skipDefaultLibCheck: true,
  moduleResolution: ts.ModuleResolutionKind.NodeJs,
};
```

And now onto our typechecking function. Some code is commented out for
concisness as it is shown in more detail above. The full typechecking code can
be found
[here](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il?file=/src/typecheck.ts).

```ts
const typecheck = (code: string): ts.Diagnostic[] => {
  // Create our virtual file system
  const dummyFilename = "file.ts";
  const files: { [name: string]: string } = {
    [dummyFilename]: code,
  };
  const sys = createSystem({ ...libs, ...files });

  // create source files from the `files` object
  const sourceFiles: { [name: string]: ts.SourceFile } = {};
  for (const name of Object.keys(files)) {
    /* ... */
  }

  // create the compiler host, an abstraction for the language service
  // to interact with the host environment
  const compilerHost: ts.CompilerHost = {
    /* ... */
  };

  // create the language service host, an absctraction of all interactions
  // between the language service and the external world
  const languageServiceHost: ts.LanguageServiceHost = {
    /* ... */
  };

  // create an instance of the TypeScript language service
  const languageService = ts.createLanguageService(languageServiceHost);

  // get all semantic diagnostics for the code we passed into this function
  const diagnostics = languageService.getSemanticDiagnostics(dummyFilename);
  return diagnostics;
};
```

And there you have it! A simple function for typechecking code in the browser with TypeScript.

## Usage

Using the above `typecheck` function on the code

```ts
const x: string = 100;
```

we get

```ts
[{
  file: SourceFileObject
  start: 6
  length: 1
  code: 2322
  category: 1
  messageText: "Type '100' is not assignable to type 'string'."
}]
```

## Improvements

Our current implementation has the overhead of re-creating the language service
everytime we call `typecheck`. An improvment we could make is to only create a
single instance of the language service and just update the contents of the
virtual file when something changes. If we can track which parts of the file
have updated, we can pass that information to the compiler via a
`ScriptSnapshot` to enable incremental parsing.

We could also use the language service to offer IDE like features in the browser with things like quick info, function documentation, JSX closing tag hints, and much more.

## Conclusion

Although getting TypeScript running in the browser is not as simple as
installing a package from NPM, with a little understaning of how the language
service works, we can get the full power of TypeScript in the browser fairly
quickly. With that we can query the compiler for type errors and access many more IDE
like features.

## Resources

- [Companion CodeSandbox](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il?file=/src/typecheck.ts)
- [Andrew's Overengineering a Blog post](https://blog.andrewbran.ch/overengineering-a-blog/#the-language-service)
- [Using the Compiler
  API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#a-minimal-compiler)
- [TypeScript Architectural Overview](https://github.com/microsoft/TypeScript/wiki/Architectural-Overview)
- [Langauge Service API](https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API)
- [Alfie](https://alfie.prodo.ai)


tags: [[web]] [[typescript]]

TypeScript in the Browser

running-ts-in-browser


# Shortener

I've wanted a custom URL shortener on jakrunzer.com for some time now. Recently I went and built a small service that does just that!

Check it out at [cheryl.fun](https://cheryl.fun/)

![[Pasted image 20210623004401.png]]

The source code is available at [github.com/coffee-cup/shortener](https://github.com/coffee-cup/shortener).

## The Stack

When starting this project, I really wanted to use [[Rust]]. I love the language but never end up using it for real projects. Not anymore!

I went with [Rocket](https://rocket.rs/) for the webserver. I've heard good things and from browsing the docs I liked how it handled state management and context throughout different routes.

For the actually shortener itself, I based my implementation off [this blog post](https://endler.dev/2017/rust-url-shortener/) but extended it to store the mapping between short code and URL in Redis. The actual implementation is fairly simple.

```rust
impl Cache for RedisRepository {
    fn store(&mut self, url: &str) -> String {
        let keys: Vec<String> = self.con.keys("*").unwrap();
        let count = keys.len() as u64;
        let hashed = self.generator.encode(&[count]);

        let _: () = self.con.set(hashed.clone(), url).unwrap();

        hashed
    }

    fn lookup(&mut self, id: &str) -> Option<String> {
        let url: Option<String> = match self.con.get(id) {
            Ok(val) => Some(val),
            Err(_e) => None,
        };

        url
    }
}
```

## Frontend

Normally my goto for frontend is [[Nextjs]]. But lately I've been really enjoying using [[Svelte]], especially for smaller projects like this.

I use Rocket static files to serve the public directory on the `/` route and then use [Rollup](https://rollupjs.org/) to bundle the Svelte into something deployable on the [[web]]. [Tailwind](https://tailwindcss.com/docs) is used to quickly style the site.

## Deployment

Of course I deployed it to [Railway](https://railway.app). I may be biased, but it deploys seamlessly with Redis hosted in the same place.

You can also deploy your own 👇

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https%3A%2F%2Fgithub.com%2Fcoffee-cup%2Fshortener&envs=BASE_URL&BASE_URLDesc=URL+that+the+site+is+hosted+at)

Shortener

shortener


# smol.css

Every time I interact with the default browser styles I am surprised just how ugly they are. I then start applying the same basic styles to de-uglify the page and _modernizing_ things like the font family, spacing, and type scale.

To speed up this process I've created `smol.css`. A drop in CSS file that you can add to any site to make it look a bit less like [the very first web page](http://info.cern.ch/hypertext/WWW/TheProject.html). It is intended to improve the look, feel, and readability of text focus sites.

You can find an example of what the CSS files does at [smol.jakerunzer.com](https://smol.jakerunzer.com). It is also available [on GitHub](https://github.com/coffee-cup/smol.css). Feel free to fork, edit, modify however you like.

A plan on extending this over time and maybe one day it will resemble an actual CSS framework. For now, it is just a simple replacement for browser styles.

tags: [[web]]

smol.css


# Static Sites

I first started web development in 2013 by learning HTML and CSS. I created
simple photography and portfolio sites with unnecessarily complicated nested
DIVs and terribly written CSS. I remember wondering why DOM elements could have
classes because I just put IDs on everything and styled them directly. Like most
[[web]] developers, my journey lead me to learn JavaScript. First JQuery, followed
by frameworks such as Angular 1, EmberJS, React, and Elm.

After learning these frameworks I was convinced that the future of the web was
single page apps. Myself, and many other developers create SPAs for the simplest
sites. I believe this trend of using the latest and greatest framework for
everything has made some of us forget just how useful dead simple static
websites can be.

## Benefits of Static Sites

- Works on all web browsers
- Small file sizes (fast)
- Works for noScript users
- Content is more cache friendly

## Benefits of JavaScript Frameworks

- Good for content that is constantly changing
- Load content without refreshing the page
- Best for web apps

## Closing Thoughts

I wrote this post so that I (and hopefully others) remember that the web was
literally created to serve static content. Only in the last 10 years have we
_hacked_ it to make it work with dynamic content.
Before immediately reaching for the newest JavaScript (or Elm) framework, take a
step back, consider all the options, and choose the best tool for the job.

tag: [[web]]

Static Sites

static-sites


# Svelte

Lightweight [[web]] framework.

svelte


# Stack Components using Twin.macro

I like to use [[tailwind-react-composition|Tailwind via twin.macro]] for styling. These are a `VStack` and `HStack` components that can be used to layout UI in [[React]].

```ts
<HStack space={4}>
  <div tw="bg-blue-500 w-20 h-20" />
  <div tw="bg-blue-500 w-20 h-20" />
  <div tw="bg-blue-500 w-20 h-20" />
</HStack>
```

## Implementation

twin.macro runs at build time so we need to define all possible styles upfront. This gives us ability to space between 0 and 16 in horizontal and vertical directions.

```ts
import tw, { TwStyle } from "twin.macro";

export interface StackProps {
  justify?: JustifyValues;
  align?: AlignValues;
  space?: StackSpace;
  className?: string;
}

type JustifyValues = "center" | "between" | "start" | "end";
type AlignValues = "center" | "start" | "end" | "baseline";

const justifyValues: Record<JustifyValues, TwStyle> = {
  center: tw`justify-center`,
  between: tw`justify-between`,
  start: tw`justify-start`,
  end: tw`justify-end`,
};

const alignValues: Record<AlignValues, TwStyle> = {
  center: tw`items-center`,
  baseline: tw`items-baseline`,
  start: tw`items-start`,
  end: tw`items-end`,
};

type StackSpace = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 12 | 14 | 16;

const vSpaces: Record<StackSpace, TwStyle> = {
  0: tw`space-y-0`,
  1: tw`space-y-1`,
  2: tw`space-y-2`,
  3: tw`space-y-3`,
  4: tw`space-y-4`,
  5: tw`space-y-5`,
  6: tw`space-y-6`,
  7: tw`space-y-7`,
  8: tw`space-y-8`,
  9: tw`space-y-8`,
  10: tw`space-y-8`,
  12: tw`space-y-12`,
  14: tw`space-y-14`,
  16: tw`space-y-16`,
};

const hSpaces: Record<StackSpace, TwStyle> = {
  0: tw`space-x-0`,
  1: tw`space-x-1`,
  2: tw`space-x-2`,
  3: tw`space-x-3`,
  4: tw`space-x-4`,
  5: tw`space-x-5`,
  6: tw`space-x-6`,
  7: tw`space-x-7`,
  8: tw`space-x-8`,
  9: tw`space-x-8`,
  10: tw`space-x-8`,
  12: tw`space-x-12`,
  14: tw`space-x-14`,
  16: tw`space-x-16`,
};

const BaseStack: React.FC<StackProps & { dir: "vertical" | "horizontal" }> = ({
  dir,
  justify,
  align,
  space,
  ...props
}) => (
  <div
    {...props}
    css={[
      dir === "vertical" ? tw`flex flex-col` : tw`flex`,
      dir === "vertical" ? vSpaces[space ?? 0] : hSpaces[space ?? 0],
      justify != null && justifyValues[justify],
      align != null && alignValues[align],
    ]}
  />
);

export const HStack: React.FC<StackProps> = props => (
  <BaseStack {...props} dir="horizontal" />
);

export const VStack: React.FC<StackProps> = props => (
  <BaseStack {...props} dir="vertical" />
);

```

tags: [[web]]