Forem: Gustavo (Guga) Guichard

Type-Safe Env Vars With Vite - A Modern Approach

Gustavo (Guga) Guichard — Fri, 14 Jun 2024 12:49:46 +0000

This post is a revamp of my previous one where I showed you how to use Zod and TS to create a type-safe environment variable system that works on both the client and server.

If you haven't read it yet, go check it out. It provides context for this post.

It's been over 18 months, and things move fast in JS land. I decided to revisit the code, update Remix itself, leverage Vite's Environment Variables, and use my new friend - ArkType - to parse the environment variables this time.

If you only want to see the code, check out the updates' diff here.

The Gist of Changes

By updating Remix from 1.7 to 2.9 and using Vite we can now use import.meta.env so we don't need to manually load the environment variables and expose them to the window anymore. That update reduces a lot of shenanigans from the previous approach.

I'm also switching from Zod to ArkType, introducing a makeTypedEnvironment helper to streamline handling environment variables in both server and client environments. Additionally, there are a few optimizations I'll be pointing out through the post.

The New `makeTypedEnvironment` Helper

This helper is designed to work seamlessly in both server and client environments, making it a versatile tool. It can handle different parsers, avoid mutating the original objects, and transform environment variable keys to camelCase.

Let's first start by making it work in multiple environments.

// lib/index.ts
// This function creates a typed environment by accepting a Zod schema parser.
function makeTypedEnvironment<T>(schema: { parse: (v: unknown) => T }) {
  // The returned function applies the schema parser to the provided environment variables.
  return (args: Record<string, unknown>): T => schema(args)
}

We can use it in both server or client:

import { z } from 'zod'
import { makeTypedEnvironment } from '~/lib'

// Define the environment Zod schema.
const envSchema = z.object({
  MODE: z.enum(['development', 'test', 'production']).default('development'),
})
// Create the environment parser using the makeTypedEnvironment helper.
const getEnv = makeTypedEnvironment(envSchema)

// Server usage: parse environment variables from process.env
const env = getEnv(process.env)
//    ^? { MODE: 'development' }

// Vite client-side env vars usage: parse environment variables from import.meta.env
const env = getEnv(import.meta.env)
//    ^? { MODE: 'development' }

You could also use getEnv(window.ENV) if you are not using Vite, just follow the instructions on the previous post.

Accepting Different Parsers and Preventing Mutations

To use it with ArkType, I'll make it accept a more generic parser as an argument.

// Function to create a typed environment that accepts a generic parser.
function makeTypedEnvironment<T>(schema: (v: unknown) => T) {
  // Spread the arguments to clone them, avoiding mutations to the original object.
  return (args: Record<string, unknown>): T => schema({ ...args })
}

The args was cloned above to avoid mutations. Some parsers, like ArkType, mutate the object (🥲) passed to them. This way, we ensure the original object is not changed.

Now we can use that function with both Zod and ArkType.

import { z } from 'zod'
import { type } from 'arktype'
import { makeTypedEnvironment } from '~/lib'

// Define the environment schema using Zod.
const envZodSchema = z.object({
  MODE: z.enum(['development', 'test', 'production']).default('development'),
})
// Create the environment parser for Zod.
const getZodEnv = makeTypedEnvironment(envZodSchema.parse)

// Define the environment schema using ArkType.
const envArkSchema = type({
  MODE: ['"development"|"test"|"production"', '=', 'development'],
})
// Create the environment parser for ArkType.
const getArkEnv = makeTypedEnvironment((d) => envArkSchema.assert(d))

Perfect!

Transforming the Env Vars to `camelCase`

For convenience, I'll use string-ts to transform the env vars to camelCase, making the usage feel more like JS code..

import { camelKeys } from 'string-ts'

// Function to create a typed environment with camelCase transformation.
function makeTypedEnvironment<T>(schema: (v: unknown) => T) {
  // Apply camelCase transformation to the parsed environment variables.
  return (args: Record<string, unknown>) => camelKeys(schema({ ...args }))
}

Now let's use the original public schema from the previous post and see how it looks like:

// environment.server.ts
import { type } from 'arktype'
import { makeTypedEnvironment } from '~/lib'

// Define the environment schema using ArkType.
const publicEnvSchema = type({
  // We prefix the keys with VITE_ to expose them in the client bundle.
  VITE_GOOGLE_MAPS_API_KEY: 'string',
  VITE_STRIPE_PUBLIC_KEY: 'string',
})
// Create the environment parser with camelCase transformation.
const getEnv = makeTypedEnvironment((d) => envSchema.assert(d))
// Parse environment variables from process.env
const env = getEnv(process.env)
//    ^? { viteGoogleMapsApiKey: string, viteStripePublicKey: string }

By leveraging string-ts, I’ve transformed the environment variable keys to camelCase, making them more intuitive to use in JavaScript code. This transformation is applied at both type and runtime levels.

Getting rid of the `VITE_` prefix

You may have noticed we are adding the VITE_ prefix to those variables that we want to be exposed to the client bundle through Vite's import.meta.env object. That comes from the Vite API and you can change the prefix if you want.

We can go further and remove that prefix as follows:

import { camelKeys, replaceKeys } from 'string-ts'

function makeTypedEnvironment<T>(schema: (v: unknown) => T) {
  // Apply replaceKeys before camelCase transformation to the parsed environment variables.
  return (args: Record<string, unknown>) =>
    camelKeys(replaceKeys(schema({ ...args }), 'VITE_', ''))
}

Check out the result:

// environment.server.ts
import { type } from 'arktype'
import { makeTypedEnvironment } from '~/lib'

// Define the environment schema using ArkType.
const publicEnvSchema = type({
  VITE_GOOGLE_MAPS_API_KEY: 'string',
  VITE_STRIPE_PUBLIC_KEY: 'string',
})
// Create the environment parser with camelCase transformation.
const getEnv = makeTypedEnvironment((d) => envSchema.assert(d))
// Parse environment variables from process.env
const env = getEnv(process.env)
//    ^? { googleMapsApiKey: string, stripePublicKey: string }

Much better!

Last Optimization: Caching

To enhance performance, I’ve implemented caching in the makeTypedEnvironment function. This prevents the schema from being reparsed every time the environment variables are accessed, resulting in faster and more efficient code execution.

This change was inspired by a comment from the first post.

import type { CamelKeys, ReplaceKeys } from 'string-ts'
import { camelKeys, replaceKeys } from 'string-ts'

// Function to create a typed environment with caching.
function makeTypedEnvironment<T>(schema: (v: unknown) => T) {
  // Instantiate a cache to store parsed environment variables.
  let cache: CamelKeys<ReplaceKeys<T, 'VITE_', ''>>

  return (args: Record<string, unknown>) => {
    // If the environment variables are already cached, return the cached value.
    if (cache) return cache

    // Otherwise, parse the environment variables and transform the keys
    const withoutPrefix = replaceKeys(schema({ ...args }), 'VITE_', '')
    const camelCased = camelKeys(withoutPrefix)
    cache = camelCased
    return cache
  }
}

You can add console.log around to see the cache in action.

Extending Schemas

We can leverage ArkType’s ability to extend schemas, simplifying the process of creating a superset of the public schema.

// environment.ts
import { type } from 'arktype'

// Define the public environment schema.
const publicEnvSchema = type({
  VITE_GOOGLE_MAPS_API_KEY: 'string',
  VITE_STRIPE_PUBLIC_KEY: 'string',
})
// Extend the public schema to create the full environment schema.
const envSchema = type(publicEnvSchema, '&', {
  MODE: ["'development'|'production'|'test'", '=', 'development'],
  SESSION_SECRET: 'string',
  STRIPE_SECRET_KEY: 'string',
})
// Create the environment parsers for public and full schemas.
const getPublicEnv = makeTypedEnvironment((d) =>
  publicEnvSchema.onUndeclaredKey('delete').assert(d)
)
const getEnv = makeTypedEnvironment((d) => envSchema.assert(d))

This approach can also be done using Zod's .extend method for comparison.

import { z } from 'zod'

// Define the public environment schema.
const publicEnvSchema = z.object({
  VITE_GOOGLE_MAPS_API_KEY: z.string(),
  VITE_STRIPE_PUBLIC_KEY: z.string(),
})
// Extend the public schema to create the full environment schema.
const envSchema = publicEnvSchema.extend({
  MODE: z.enum(['development', 'production', 'test']).default('development'),
  SESSION_SECRET: z.string(),
  STRIPE_SECRET_KEY: z.string(),
})
// Create the environment parsers for public and full schemas.
const getPublicEnv = makeTypedEnvironment(
  publicEnvSchema.onUndeclaredKey('delete').parse,
)
const getEnv = makeTypedEnvironment(envSchema.parse)

We are using ArkType's .onUndeclaredKey('delete') to remove undeclared keys from the object so we avoid exposing secrets to the client.

ArkType's default strategy is called Loose Assertion while Zod will omit undeclared keys by default - Safe Parsing.

Et Voilà

Thanks to Vite, we can go ahead and remove a bunch of code from the previous post.

Now, anywhere in your code, you can access the public environment variables in a type-safe way:

// app/routes/index.tsx
import { getPublicEnv } from '~/environment'

export default function Index() {
  function showStripeKey() {
    alert(
      `Stripe key on the client: ${
        getPublicEnv(import.meta.env).stripePublicKey
      }`,
    )
  }

  return (
    <div>
      <h1>
        GMAPS key on the server and client:{' '}
        {getPublicEnv(import.meta.env).googleMapsApiKey}
      </h1>
      <p>
        <button onClick={showStripeKey}>Alert Stripe key</button>
      </p>
    </div>
  )
}

That's It

Now we have a faster, solid, type-safe environment variable system that works on both the client and server environments. And with a great DX:

Another benefit of this approach is that you don't need to keep an .env.sample file as you can always check the environment.ts file to know what environment variables are required.

We also learned how to create functions that accept different parsers, which is a good practice, especially for library authors.

I'd love to hear your thoughts on this. If you have any questions or suggestions, please leave a comment below.

Update: `make-typed-env` on npm

Since writing this article, I've extracted the makeTypedEnvironment pattern into a standalone library: make-typed-env.

It builds on the same ideas but with a few improvements:

Works with any schema library via Standard Schema — Zod, ArkType, Valibot, and more
Key transformation is a parameter — pass camelKeys, replaceKeys, or any function instead of hardcoding the behavior - Zero runtime dependencies — just 0.5 KB

npm install make-typed-env

import { makeTypedEnv } from "make-typed-env"
import { camelKeys, replaceKeys } from "string-ts"
import { z } from "zod"

const getEnv = makeTypedEnv(
  z.object({
    VITE_STRIPE_PUBLIC_KEY: z.string(),
    VITE_SENTRY_DSN: z.string().optional(),
  }),
  (parsed) => camelKeys(replaceKeys(parsed, "VITE_", "")),
)

const env = getEnv(import.meta.env)
// env.stripePublicKey → string
// env.sentryDsn       → string | undefined

Check it out on GitHub.

Using Arktype in Place of Zod - How to Adapt Parsers

Gustavo (Guga) Guichard — Wed, 12 Jun 2024 16:37:14 +0000

Ever since I started using Zod, a TypeScript-first schema declaration and validation library, I've been a big fan and started using it in all my projects. Zod allows you to ensure the safety of your data at runtime, extending TypeScript’s type-checking capabilities beyond compile-time. Whenever I need to validate data from an outside source, such as an API, FormData, or URL, Zod has been my go-to tool.

I created, co-created, and worked on entire OSS libraries that are based on the principle of having strong type checking at both type and runtime levels.

A newfound love

Arktype has been on my radar for a while now, it offers similar validation capabilities but with some unique features that caught my eye, like the way it lets you define validators using the same syntax you use to define types.

I finally got the chance to use it in a project, and it was delightful.

The deal is that I'm using those Zod based libraries in the project, and I wanted to see how I could adapt them to use Arktype where they expect a schema.

I never wanted to have a tight coupling between the libraries and Zod, so instead of having Zod as a dependency, I'd expect a subset of a Zod schema.

// instead of:
function validate<T>(schema: ZodSchema<T>): T {
  // ...
}

// I'd expect something like:
function validate<T>(schema: { parse: (val: unknown) => T }): T {
  // ...
}

The validate function now accepts a generic schema that only requires a parse method. This decouples our code from Zod, allowing us to use other libraries with minimal changes.

It turns out this has just proven to be a great idea.

The libraries I'm adapting for

In this project, I'm using two Zod-based libraries, which are:

make-service

This lib uses Zod to validate an API response - among other nice features -, which is useful to ensure the data expectations are correct.

Check out a code sample without the library:

const response = await fetch('https://example.com/api/users', {
  headers: {
    Authorization: 'Bearer 123',
  },
})
const users = await response.json()
//    ^? any

And with it:

const service = makeService('https://example.com/api', {
  headers: {
    Authorization: 'Bearer 123',
  },
})

const response = await service.get('/users')
const users = await response.json(usersSchema)
//    ^? User[]

composable-functions

This is a library to allow function composability and monadic error handling. If you don't know it yet, think about a smaller/simpler Effect which has runtime type checking backed in by Zod.

Here follows a didactic example of how to define a function that doubles a number and does runtime type-checking:

import { withSchema } from 'composable-functions'
const safeDouble = withSchema(z.number())((n) => n * 2)

The difference between the libraries

When going into the libs source we can see that they use different subsets of Zod. The first one expects the already mentioned:

type Schema<T> = { parse: (d: unknown) => T }

While the second one expects the following code which is a subset of Zod's SafeParseError | SafeParseSuccess:

type ParserSchema<T = unknown> = {
  safeParse: (a: unknown) =>
    | {
        success: true
        data: T
      }
    | {
        success: false
        error: {
          issues: ReadonlyArray<{
            path: PropertyKey[]
            message: string
          }>
        }
      }
}

Which is a bit more complex, but still, it's just a subset of Zod.

TDD: Type Driven Development 😄

When investigating on how to extract the type out of an Arktype schema, I found out you can do:

import { Type } from 'arktype'

type Example = Type<{ name: string }>
type Result = Example['infer']
//   ^? { name: string }

Therefore, I could go on and create one adaptor for each library but this is a case where I can join both expectations in the same function. In fact, what I need is a function that conforms to this return type:

import { Type } from 'arktype'
import { ParserSchema } from 'composable-functions'
import { Schema } from 'make-service'

declare function ark2zod<T extends Type>(
  schema: T,
): Schema<T['infer']> & ParserSchema<T['infer']>

The implementation

Having started from the types above, the solution was quite straightforward.
I hope the code with comments below speaks for itself:

import { type, Type } from 'arktype'
import { ParserSchema } from 'composable-functions'
import { Schema } from 'make-service'

function ark2zod<T extends Type>(
  schema: T,
): Schema<T['infer']> & ParserSchema<T['infer']> {
  return {
    // For `make-service` lib:
    parse: (val) => schema.assert(val),
    // For `composable-functions` lib:
    safeParse: (val: unknown) => {
      // First, we parse the value with arktype
      const data = schema(val)
      // If the parsing fails, we only need what ParserSchema expects
      if (data instanceof type.errors) {
        // The ArkErrors will have a shape similar to Zod's issues
        return { success: false, error: { issues: data } }
      }
      // If the parsing succeeds, we return the successful side of ParserSchema
      return { success: true, data }
    },
  }
}

export { ark2zod }

Special thanks to David Blass - ArkType's creator - who reviewed and suggested a leaner version of this adapter.

Usage

Using the function above I was able to create my composable functions with make-service's service using Arktype schemas seamlessly:

import { type } from 'arktype'
import { withSchema } from 'composable-functions'
import { ark2zod } from '~/framework/common'
import { blogService } from '~/services'

const paramsSchema = type({
  slug: 'string',
  username: 'string',
})

const postSchema = type({
  title: 'string',
  body: 'string',
  // ...
})

const getPost = withSchema(ark2zod(paramsSchema))(
  async ({ slug, username }) => {
    const response = await blogService.get('articles/:username/:slug', {
      params: { slug, username },
    })
    const json = await response.json(ark2zod(postSchema))
    return json
  },
)

export { getPost }

When using the getPost function, my result will be strongly typed at both type and runtime levels or it will be a Failure:

export function loader({ params }: LoaderFunctionArgs) {
  const result = await getPost(params)
  if (!result.success) {
    console.error(result.errors)
    throw notFound()
  }
  return result.data
  //            ^? { title: string, body: string, ... }
}

Final thoughts

I hope this post was helpful to you, not only to understand how to adapt Zod-based libraries but also to understand how we at Seasoned approach problems. If you have any questions or have gone through a similar migration, I’d love to hear about your experiences and any tips you might have.

One thing I can assure you is that we love TS and we like to be certain about our data, be it at compile time or runtime.

Enforcing 'noImplicitAny' on callbacks to generic functions

Gustavo (Guga) Guichard — Mon, 10 Jun 2024 20:38:24 +0000

One of the first errors every TypeScript developer encounters is the famous noImplicitAny, which happens when you don't specify a type for a variable. For example:

function fn(s) {
  //        ^? Parameter 's' implicitly has an 'any' type.
  console.log(s.subtr(3));
}

This is a great thing because it forces you to think about the types of your variables and functions, helping you avoid bugs.

The problem

When developing your own functions that receive a callback, you might lose that error checking if you specify the type of the callback as (...args: any[]) => any. This type indicates that the function can receive any number of arguments of any type.

// @ts-expect-error
function fn(a) {}
const wrapper = (f: (...args: any[]) => any) => f
const test = wrapper((a) => {})
//                    ^? any
// TS won't complain

If you don't know, (...args: any[]) => any is one of the most popular ways to type a function. The Function primitive is not recommended because it can accept anything that is callable, such as a constructor, a callable object, or even a non-callable class such as Map.
But this use case creates a bad developer experience because you're losing one of the basic benefits of the type system. An any can easily go unnoticed and cause bugs further down the line.

The quest

Last week, I started a Twitter thread about this and asked for help from some friends and TS experts.
I was working on our library composable-functions on an issue by @danielweinmann that was experiencing this problem.

The problem seemed impossible and the solutions would require some trade-offs.

Forbidding the use of any in the callback's arguments was reasonable since the library I was working on is for strict TypeScript projects and any is probably out of the question. However, it would be a breaking change for the users and quite strict.
Swapping (...args: any[]) => any for (...args: never[]) => unknown. This was suggested by our contributor @jly36963 which is a thread on the TS repo itself. It seems nice because if you don't declare the types, the arguments are gonna be never, so you can't use them within the function. There was one concern though, this solutions causes problems with default arguments - as you can read in the last comment on that thread.

This is when I decided to go bold and try that Function primitive!

The solution

The solution was to use it in the function parameter but restrict it anywhere else down the line. We only need to enforce noImplicitAny in the declaration of the callback, but we have other ways to enforce a narrower type, such as (...args: any[]) => any, elsewhere.

The diff was quite simple:

-function composable<T extends (...args: any[]) => any>(fn: T): Composable<T> {
+function composable<T extends Function>(
+  fn: T,
+): Composable<T extends (...args: any[]) => any ? T : never> {

And it worked! The error was back and the user would have to specify the types of the arguments of the callback.

If the user tried to use something which isn't an actual function, they would get a Composable<never> which is impossible to work with.

You can check the final PR here

Conclusion

There were two motivations to write this post:

I couldn't find any information about this on the internet.
I love simple solutions that require you to think outside the box and break some rule as long as you cover up for them.

I hope this post can help someone else who is struggling with the same problem.

Why you should use Remix Full-Stack: Improved Productivity and Collaboration

Gustavo (Guga) Guichard — Wed, 04 Jan 2023 19:30:34 +0000

Earlier today I saw this tweet:

// Detect dark theme var iframe = document.getElementById('tweet-1609862646228213765-115'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1609862646228213765&theme=dark" }

And although I have a lot of respect for the tweet author and for RoR itself I felt like expressing my opinion about why I hope Shopify won't walk that path.

TLDR

In this post I write about our experiences with using a Rails API and separate front-end app:

Complex hiring process due to the need for specialized front and back end developers
Communication issues between the front and back end
Duplication of code for tasks such as validation, authorization, and type definitions
Maintaining two separate deployment processes and hosting solutions

I also highlight some benefits of adopting Remix as a full stack framework:

Improved developer experience and greater type-safety
Simplified hiring process with the ability for any developer to contribute to the full stack
Elimination of the need for two separate deployment processes and hosting solutions

And explain the opportunities and challenges of filling in the gaps left by the absence of Rails.

Rails: The Good Ol' Days

We've all been there.

Fifteen(ish) years ago, we would develop any web app in a monolithic codebase. Every new web developer would be able to contribute to both the back-end and front-end on their first day because they would know the architecture, where every bit of code belonged, and the responsibilities of models, views, controllers, and services, etc.

If we wanted a production-ready app, we would extend Rails' built-in features with our favorite gems.

The front end was not that complex. We would just sprinkle in a bit of JS and use some libraries like jQuery, BackboneJS, or compilers like CoffeeScript. Progressive enhancement was almost a side effect of the development process.

However, this didn't last long because we wanted a richer UX, and so we entered the SPA era. I'm not going to go into the pros and cons of SPAs, as many people have already done so, but I want to explain why it was a problem for us.

Our Business Problem with SPAs

While we were solving all of our back-end needs with Rails APIs, we were also surfing the React wave, using Flux, Redux, Webpack, CRA, SSR solutions, Flow, TS, and a plethora of packages and tools to stay on the cutting edge of technology.

Our hiring process became a lot more complex because we needed to hire for both the front and back end. It was almost impossible for a developer to be as productive in both stacks, which created little developer silos and made the change of context to deliver any full-stack feature enormous.

We also realized that about 90% of the calls for help in our #devhelp Slack channel had to do with the communication between the apps. Managing the state in the front end and keeping it in sync with the database was the real bottleneck of web development.

There was also a lot of duplication, as things like validations, authorization, and type definitions would have to be done on both apps.

Having two teams, two deployment processes, and two hosting solutions was a hassle, and even using BFF (backend-for-frontend) didn't help much.

We also tried out Hotwire, but it didn't come close to the DX/UX we're used to with React.

Our Urge for a New Stack

As TypeScript evolved and we became proficient with it, we realized the huge benefits we would get if we had our whole stack using it.

So, when Remix came to our attention, we decided to allocate two of our most seasoned developers to do daily R&D to see if Remix would fall short. This process lasted for a year!

During that time, we threw the most complex business problems at ourselves and created some public libraries as well as an internal framework. We figured out ways to migrate CRA + Rails apps to Remix.

After all that time and investment, we feel more confident about our stack than ever!

You Might Not Get the Full Potential of Remix

The DX (developer experience) we achieved is unmatched. We have type-safety from end to end and no code duplication. These two things alone would not be possible with a BFF approach.

Our hiring process is shaping up a lot simpler, and all the developers will be speaking the same language now. Like in the Rails era, any developer will be able to contribute full stack.

We also ditched the cost of maintaining two deployments and hosts per app.

Remix Opened the Door to the Back-end World

To achieve this, we had to find solutions to fill in the gaps left by the absence of Rails. We had to use tools like Prisma, Node mailer, MJML, Bull, etc., because Remix is not a (complete) backend framework.

We had to figure out our architecture, file organization, and recreate some things that Rails had mastered over the years.

We still miss the power of ActiveRecord, but we know that our inferred type safety has been preventing a lot more bugs. We are also aware that we now spend most of our time developing business logic instead of the accidental complexity inherent in SPAs.

As a bonus benefit, we not only re-added progressive enhancement to our vocabulary, but we also have been able to use techniques that we developed in the Rails era - AKA: web standards.

Conclusion

The reason why I hope Shopify will use Remix as a full-stack framework is that not every small company can afford to invest as much as we did at Seasoned in order to achieve the dream stack. If Shopify does it, it will be a huge win for the community, and it will also lower the barrier to entry for small companies to achieve the same DX.

We need a framework on top of Remix! It will happen eventually, whether it's Shopify or companies like Seasoned that do it.

If you see the value in a Remix (or React Router 6.4+) and TypeScript stack, but you are still figuring out how to get there or can't afford to do this research, talk to us in our discord community.

Type-safe environment variables on both client and server with Remix

Gustavo (Guga) Guichard — Mon, 14 Nov 2022 14:09:20 +0000

If you are running Remix on Vite, I have an updated post with a simpler, leaner way to get env vars on the client. Check it out!

In this post we are going to use TypeScript to:

strongly type our process.env variables
expose some public variables from the server to the client, keeping autocomplete all the way

In case you just want to check the final solution, the source code is at the end of the post

As with most Remix tutorials, the contents of this post are not coupled to Remix in any way. If you want to expose env variables from the server to the client this approach might be suitable to your app.

Baseline

Let's say we have some environment variables in our .env file:

# .env
SESSION_SECRET="s3cret"
GOOGLE_MAPS_API_KEY="somekey"
STRIPE_PUBLIC_KEY="should be exposed"
STRIPE_SECRET_KEY="shouldn't be exposed"

We want to expose some of them to the client so we can use some client libraries. All the secret tokens should dwell on the server-side only, but we can safely expose STRIPE_PUBLIC_KEY and GOOGLE_MAPS_API_KEY.

If you don't know how to expose environment variables to the browser with Remix, I recommend you to stop here and take a quick look at the official approach or even Sergio's post prior to reading this post.

By following that approach we end up with this code:

// app/root.tsx
export function loader() {
  return json({
    publicKeys: {
      GOOGLE_MAPS_API_KEY: process.env.GOOGLE_MAPS_API_KEY,
      STRIPE_PUBLIC_KEY: process.env.STRIPE_PUBLIC_KEY,
    }
  })
}

export default () => {
  const { publicKeys } = useLoaderData<typeof loader>()
  return (
    <html lang="en">
      <body>
        <script
          dangerouslySetInnerHTML={{
            __html: `window.ENV = ${JSON.stringify(publicKeys)}`,
          }}
        />
        {/* ... App ... */}
        <Scripts />
      </body>
    </html>
  )
}

And it works at runtime, yay!

However, on behalf of all the typescript junkies out there, we can't stop here as we shall have type-safety and autocomplete ~~for breakfast~~ for both client and server.

Take a look at types inferred from process.env:

We can do better than that!

Type-safe process.env

IMO there's no better way to validate data structures on both type level and runtime as Zod. So let's go ahead and install it:

npm install --save zod

Now we can express our .env file in a zod schema and have a function to return the parsed values from that file. Create a new file as follows:

// app/environment.server.ts
import * as z from 'zod'

const environmentSchema = z.object({
  NODE_ENV: z
    .enum(['development', 'production', 'test'])
    .default('development'),
  SESSION_SECRET: z.string().min(1),
  GOOGLE_MAPS_API_KEY: z.string().min(1),
  STRIPE_PUBLIC_KEY: z.string().min(1),
  STRIPE_SECRET_KEY: z.string().min(1),
})

const environment = () => environmentSchema.parse(process.env)

export { environment }

And then update the root.tsx's loader function to use that new helper:

// app/root.tsx
export function loader() {
  return json({
    publicKeys: {
      GOOGLE_MAPS_API_KEY: environment().GOOGLE_MAPS_API_KEY,
      STRIPE_PUBLIC_KEY: environment().STRIPE_PUBLIC_KEY,
    },
  })
}

By doing so, we've achieved some benefits:

We now have strongly typed environment variables at the server-side
We have a nice documentation of .env file and we can now ditch the .env.sample file
Since peers won't run the app without the required env vars, there will be no surprises at runtime

Check out how much narrower our environment variables got:

The problem is that we are exposing some variables to the browser but TypeScript doesn't know about them yet:

Let's fix it.

Type-safe window.ENV

To let TypeScript know that our window now has access to those values, we can extend the global Window interface:

declare global {
  interface Window {
    ENV: {
      GOOGLE_MAPS_API_KEY: string
      STRIPE_PUBLIC_KEY: string
    }
  }
}

And we now have code completion for the window.ENV variables:

The `<PublicEnv />` component

Let's create a new React component to keep all the logic related to browser environment variables in a single file.

We can even bring the global declaration here and it will work across the whole app:

// app/ui/public-env.tsx
declare global {
  interface Window {
    ENV: Props
  }
}
type Props = {
  GOOGLE_MAPS_API_KEY: string
  STRIPE_PUBLIC_KEY: string
}
function PublicEnv(props: Props) {
  return (
    <script
      dangerouslySetInnerHTML={{
        __html: `window.ENV = ${JSON.stringify(props)}`,
      }}
    />
  )
}

Notice the Props type has the exact values we want to expose to the window.

Now we update our root.tsx file to use that component instead of the <script /> tag:

// app/root.tsx
export default () => {
  const { publicKeys } = useLoaderData<typeof loader>()
  return (
    <html lang="en">
      <body>
        <PublicEnv {...publicKeys} />
      </body>
    </html>
  )
}

As you can see, everything is strongly typed:

However, if we run the code above (with the console.log) we are going to see an error:

As you might've guessed, we can't access window on the server - not talking about you, Deno 🦕 👀 - the same way we can't access process.env in the browser.

Universal environment variables

I'm not sure I like this term but universal has been used quite often to mean a piece of code that can run on both client and server seamlessly.

We need a function that returns us the contents of window.ENV when the runtime does have access to window or the contents of process.env otherwise. Let's create it in the same file as the <PublicEnv /> component:

// app/ui/public-env.tsx
function getPublicEnv<T extends keyof Props>(key: T): Props[T] {
  return typeof window === 'undefined'
    ? environment()[key]
    : window.ENV[key]
}

By using a generic T extends keyof Props we get code completion when calling getPublicEnv:

But if we tell TS that window.ENV is available without actually checking it we are lying to ourselves. What if someone removes the <PublicEnv /> component from the root.tsx or places the component below the <Scripts /> component?

Let's add that check:

// app/ui/public-env.tsx
function getPublicEnv<T extends keyof Props>(key: T): Props[T] {
  if (typeof window !== 'undefined' && !window.ENV) {
    throw new Error(
      `Missing the <PublicEnv /> component at the root of your app.`,
    )
  }

  return typeof window === 'undefined'
    ? environment()[key]
    : window.ENV[key]
}

Now we throw a friendly error message to our fellow peers in case they mess up with our dear component:

Strongly-typed universal environment variables unlocked, yay!

Final touches

There's still one thing that bothers me. We must keep track of the exposed env vars in two places: the loader function of root.tsx and the Props type of public-env.tsx. Whenever we change one of them we have to tweak the other.

Let's take care of that.

We are going to need a function to pick which variables of our environment are going to make it to the browser. Let's create that function:

function typedPick<T extends {}, U extends Array<keyof T>>(obj: T, keys: U) {
  let result = {} as Pick<T, U[number]>
  for (const key of keys) {
    result[key] = obj[key]
  }
  return result
}

Then, we create a function to return only the env vars that are to be exposed. We co-locate it with the environment function so we keep a single file responsible for that subject:

// app/environment.server.ts

function getPublicKeys() {
  return {
    publicKeys: typedPick(environment(), [
      'STRIPE_PUBLIC_KEY',
      'GOOGLE_MAPS_API_KEY',
    ]),
  }
}

Update the root.tsx's loader function to use getPublicKeys:

// app/root.tsx
export function loader() {
  return json(getPublicKeys())
}

And we can now derive the <PublicEnv />'s Props type out of that new function. Let's update that file:

// app/ui/public-env.tsx
type Props = ReturnType<typeof getPublicKeys>['publicKeys']
declare global {
  interface Window { ENV: Props }
}

Done! We now have a single source of truth for our universal environment variables.

Check out the resulting DX:

We change one single file and let TypeScript have our backs throughout the App.

That's it 🔥

Let me know what you think about this post in the comments below. I'll be happy to get some feedback, help, and suggestions.

Remix is still quite new and we are figuring stuff out on the go, but I can't help but smile whenever I realize that finding out how to do something with Remix is actually finding out how to do something on the web 🤓

Check the repo on github

Creating a Github-like Progress bar for your Remix app

Gustavo (Guga) Guichard — Thu, 04 Aug 2022 14:24:10 +0000

This post is about the progress bar that shows at the top of the cover image 🤓

This is a follow-up post

If you haven't read the first post, go check it out: Add a Global Progress indicator to your Remix app

Intro

Now that we know how to create a global progress indicator in our Remix apps we want to get a little fancy.

Creating a progress bar with actual download/upload percentage can be quite tricky. But with just a few adjustments in our GlobalLoading component, leveraging the possible states of navigation.state we can achieve a much better UX.

Start by styling it properly

Change the returning JSX of the component on the previous post.

<div
  role="progressbar"
  aria-hidden={!active}
  aria-valuetext={active ? "Loading" : undefined}
  className="fixed inset-x-0 top-0 z-50 h-1 animate-pulse"
>
  <div
    className={cx(
      "h-full bg-gradient-to-r from-blue-500 to-cyan-500 transition-all duration-500 ease-in-out",
      active ? "w-full" : "w-0 opacity-0 transition-none"
    )}
  />
</div>

We changed a little bit, we are not going to be using that spinner SVG anymore, now we just need a div with some style in our progress bar container. The main changes are:

fixed inset-x-0 top-0: we are positioning the container at the top.
animate-pulse: from tailwind to give the bar another touch of "looking busy"

And now the transition classes transition-all duration-500 ease-in-out are placed on the child div because that is what we are going to be animating.

It should now be looking like the following:

The problem is the timing of the animation (500ms) does not follow the timing of the request/response and the animation is linear. We want to add a few stops on the way so it feels more like an actual progress bar.

Introducing `navigation.state`

Other than the "idle", there are couple more states we can be aiming for so the progress bar will actually feel like "progressing". By just changing the code a little bit we already add a step on the way:

<div role="progressbar" {...}>
  <div
    className={cx(
      "h-full bg-gradient-to-r from-blue-500 to-cyan-500 transition-all duration-500 ease-in-out",
      navigation.state === "idle" && "w-0 opacity-0 transition-none",
      navigation.state === "submitting" && "w-1/2",
      navigation.state === "loading" && "w-full"
    )}
  />
</div>

When the network is idle, the progress bar has a width of 0 and is transparent. We also add transition-none at this stage so the bar doesn't animate back from w-full to w-0.

When there's some sort of form submission, the bar will animate from w-0 to w-1/2 in 500ms and when the loaders are revalidating it will transition from w-1/2 to w-full.

It already looks quite cool:

Now the bar animates from w-0 to w-full when only a loader is dispatched and will stop in the middle of the way if we are sending data to the server! Again, Remix is here for us!

I wish there was the 4th step

I'd like the progress bar to stop in 2 places though, so it feels more like Github's. The problem is we don't have an extra state in navigation.

What I really want to tell the computer is:

during the request animate from 0 to 25%-ish
during the response animate till 75%-ish
when going idle again quickly go all the way to 100% and disappear. 🤔

Yes, this can be done, we just need to manufacture that last step!

I'll call this variable animationComplete and show how to use it, later I'll show how to define it:

<div
  className={cx(
    "h-full bg-gradient-to-r from-blue-500 to-cyan-500 transition-all duration-500 ease-in-out",
    navigation.state === "idle" &&
      animationComplete &&
      "w-0 opacity-0 transition-none",
    navigation.state === "submitting" && "w-4/12",
    navigation.state === "loading" && "w-10/12",
    navigation.state === "idle" && !animationComplete && "w-full"
  )}
/>

Ok, how are we gonna do this?

There is an API for DOM elements called Element.getAnimations that can be mapped to return an array of promises that will be settled when the animations are finished!

Promise.allSettled(
  someDOMElement
    .getAnimations()
    .map((animation) => animation.finished)
).then(() => console.log('All animations are done!')

With a little ref from my friend React to get the DOM element and some React state we can get the job done! Here's the updated code for the component:

import * as React from "react";
import { useNavigation } from "@remix-run/react";
import { cx } from "~/utils";

function GlobalLoading() {
  const navigation = useNavigation();
  const active = navigation.state !== "idle";

  const ref = React.useRef<HTMLDivElement>(null);
  const [animationComplete, setAnimationComplete] = React.useState(true);

  React.useEffect(() => {
    if (!ref.current) return;
    if (active) setAnimationComplete(false);

    Promise.allSettled(
      ref.current.getAnimations().map(({ finished }) => finished)
    ).then(() => !active && setAnimationComplete(true));
  }, [active]);

  return (
    <div role="progressbar" {...}>
      <div ref={ref} {...} />
    </div>
  );
}

export { GlobalLoading };

Understanding the important parts

We already had the first 2 lines defining navigation and active. We now added:

The useRef to store the DOM element of the inner div
A definition of the animationComplete state
A useEffect that will run whenever the active state of the navigation changes from idle and back. In this effect we:
- set the animationCompleted state to false to start
- wait for all the animations of the ref element to be completed so we can set animationCompleted back to true. This only happens if navigation.state is idle again.

That's it! Now we have our progress bar in 4 steps with just a bit of code:

The final code

import * as React from "react";
import { useNavigation } from "@remix-run/react";
import { cx } from "~/utils";

function GlobalLoading() {
  const navigation = useNavigation();
  const active = navigation.state !== "idle";

  const ref = React.useRef<HTMLDivElement>(null);
  const [animationComplete, setAnimationComplete] = React.useState(true);

  React.useEffect(() => {
    if (!ref.current) return;
    if (active) setAnimationComplete(false);

    Promise.allSettled(
      ref.current.getAnimations().map(({ finished }) => finished)
    ).then(() => !active && setAnimationComplete(true));
  }, [active]);

  return (
    <div
      role="progressbar"
      aria-hidden={!active}
      aria-valuetext={active ? "Loading" : undefined}
      className="fixed inset-x-0 top-0 left-0 z-50 h-1 animate-pulse"
    >
      <div
        ref={ref}
        className={cx(
          "h-full bg-gradient-to-r from-blue-500 to-cyan-500 transition-all duration-500 ease-in-out",
          navigation.state === "idle" &&
            animationComplete &&
            "w-0 opacity-0 transition-none",
          navigation.state === "submitting" && "w-4/12",
          navigation.state === "loading" && "w-10/12",
          navigation.state === "idle" && !animationComplete && "w-full"
        )}
      />
    </div>
  );
}

export { GlobalLoading };

I hope you've found these 2 posts useful! I'd love to know if you happen to add this code to your project or even evolve it or come up with better solutions. Do let me know 😉

PS: To see the full code for both posts, check out this pull request.

Add a Global Progress indicator to your Remix app

Gustavo (Guga) Guichard — Thu, 04 Aug 2022 14:18:00 +0000

This post is about the spinner at the bottom left corner of the cover image 🤓

Disclaimer: there's a follow-up post for this one

Check it out later: Creating a Github-like Progress Bar for your Remix app

Intro

At Seasoned we are always looking for ways to deliver better UX/DX with less code and that is one of the main reasons we've been investing a lot in Remix.

One very nice recent addition to our Remix apps was a global progress indicator. By leveraging Remix's Form and Fetchers we have a single source of truth for any roundtrip the browser may be doing to the server.

Therefore, by just dropping a little component at our app/root.tsx file we can show a subtle progress indicator - I'm not talking about those obtrusive spinners the "SPA era" got us so used to, but something more similar to the browser's native tab spinner - whenever the page is loading/refreshing.

Got it, show me the code!

Preparation

I bootstrapped a new Remix app using the Indie Stack which already has tailwind installed as we are going to use it in this exercise.

After creating the repo, I added our cx utility function for composing classes and also created a sleep helper so I can better test the spinners locally:

// app/utils.ts
const sleep = (time: number) =>
  new Promise((resolve) => setTimeout(resolve, time));

export { sleep }

Using the sleep method in places I want to simulate a slow backend activity:

// Add this to any loaders and actions
export async function loader({ request }: LoaderArgs) {
  await sleep(1000);
  return json({
    // ..
  });
}

export async function action({ request }: ActionArgs) {
  await sleep(1000);
  return json({
    // ..
  });
}

The GlobalLoading component

I'm just going to add the component code here and explain the important parts later:

import { useNavigation } from "@remix-run/react";
import { cx } from "~/utils";

function GlobalLoading() {
  const navigation = useNavigation();
  const active = navigation.state !== "idle";

  return (
    <div
      role="progressbar"
      aria-valuetext={active ? "Loading" : undefined}
      aria-hidden={!active}
      className={cx(
        "pointer-events-none fixed left-0 bottom-0 z-50 p-4 transition-all duration-500 ease-out",
        active ? "translate-y-0" : "translate-y-full"
      )}
    >
      <svg
        className="h-7 w-7 animate-spin"
        xmlns="http://www.w3.org/2000/svg"
        fill="none"
        viewBox="0 0 24 24"
        width="1em"
        height="1em"
      >
        <circle
          className="stroke-blue-600/25"
          cx={12}
          cy={12}
          r={10}
          strokeWidth={4}
        />
        <path
          className="fill-blue-600"
          d="M4 12a8 8 0 0 1 8-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 0 1 4 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
        />
      </svg>
    </div>
  );
}

export { GlobalLoading };

The Spinner

First of all, the SVG is the "official" Tailwind spinner from their docs, nothing special about it.

The `active` state

This is easy. Thanks to Remix and their useNavigation hook, we know that whenever the navigation.state !== 'idle' that means there's some loader/action validating.

`aria-*` stuff

We added role="progressbar", aria-valuetext and aria-hidden with values based on the active state so we can bring some semantics to any a11y device that may be screening our app.

The Tailwind classes

The core of the component's functionalities lies in tailwind classes.

className={cx(
  "pointer-events-none fixed left-0 bottom-0 z-50 p-4 transition-all duration-500 ease-out",
  active ? "translate-y-0" : "translate-y-full"
)}

Of course, we don't really need TW for this, but I'm going to assume you know a little of it:

pointer-events-none fixed left-0 bottom-0 z-50: we want it to be on the bottom-left corner of the app, floating above any content but not blocking any mouse/touch interaction with the rest of the page.
transition-all duration-500 ease-out: to animate the entrance and disappearance of the spinner.
active ? "translate-y-0" : "translate-y-full": when the spinner is active it shows up at its original position, otherwise it moves down in the Y axis at a distance equal to the size of the spinner container

Et voilá

Now we just need to import and add this component once and that's it:

// app/root.tsx
import { GlobalLoading } from "./components/global-loading";

export default function App() {
  return (
    <html lang="en" className="h-full">
      <head />
      <body className="h-full">
        <GlobalLoading />
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        <LiveReload />
      </body>
    </html>
  );
}

This component is very simple yet it gives a little boost to the overall UX of your app. We don't ever need to think about it again as we know that even if we forget or don't have time to do progressive enhancement in every feature of our app, our foundational UX is solid.

That is exactly what we love about Remix.

We can dive deeper

In the next post I expand on this subject so we can create a progress bar similar to Github's:

Check it out

How domain-functions improves the (already awesome) DX of Remix projects?

Gustavo (Guga) Guichard — Fri, 06 May 2022 23:33:21 +0000

At Seasoned we are absolutely in love with Remix. We have been working with it for a few months and we really think it is a great tool.
But as with anything we'd use, we've found a few areas where we think the out-of-the-box approach falls short.

In this post, I'm gonna talk about some of them and show how we are solving those problems with our new library: domain-functions.

Plumbing

As soon as any project starts to get a little serious a demand for a structured architecture starts to emerge. On almost every example of Remix's actions and loaders out there, we can see some boilerplate we call plumbing.

For instance, take a look at the action on this chunk of code of the Jokes App. A lot is going on! And this is usually how Remix Apps look, relaying a lot of responsibility to the controllers.

Let's put the common loader/action's responsibilities in perspective:

A) Extracting data out of the request, be it from the query string, the body, the url, request headers, etc.
B) Assert that this data is in the right format, maybe doing some data munging after that.
C) Doing some side effects, such as inserting data into the database, sending emails, etc.
D) Returning a different Response depending on the result of previous steps.
E) There's also a need to manually maintain the types of your Responses aligned with what the UI expects, we'll talk more about it later in this post.

As you've probably guessed already, we think about loaders and actions as controllers. And we think controllers should only "speak HTTP". In that mindset, we'd refactor the list above to only steps A and D. Steps B and C are what we call Business logic, the code which makes the project unique.

And at Seasoned we like to separate this code into well defined/tested/typed domains.

So how would we decouple that business logic with `domain-functions`?

First, we'd write Zod schemas for both the user input and the environment data:

// app/domains/jokes.server.ts
const jokeSchema = z.object({
  name: z.string().min(2, `That joke's name is too short`),
  content: z.string().min(10, 'That joke is too short'),
})

const userIdSchema = z.string().nonempty()

Then we'd write the business logic using those schemas:

// app/domains/jokes.server.ts
import { makeDomainFunction } from 'domain-functions'
// ...

const createJoke = makeDomainFunction(jokeSchema, userIdSchema)
  ((fields, jokesterId) =>
    db.joke.create({ data: { ...fields, jokesterId } })
  )

And lastly we'd write the controller's code:

// app/routes/jokes/new.tsx
import { inputFromForm } from 'domain-functions'
// ...

export async function action({ request }: ActionArgs) {
  const result = await createJoke(
    await inputFromForm(request),
    await getUserId(request),
  )
  if (!result.success) {
    return json(result, 400)
  }
  return redirect(`/jokes/${result.data.id}?redirectTo=/jokes/new`)
}

Now, let's rewrite this loader. We start with the domain:

// app/domains/jokes.server.ts
const getRandomJoke = makeDomainFunction(z.null(), userIdSchema)
  (async (_i, jokesterId) => {
    const count = await db.joke.count()
    const skip = Math.floor(Math.random() * count)
    return db.joke.findMany({ take: 1, skip, where: { jokesterId } })
  })

Then, the loader:

// app/routes/jokes/index.tsx
export async function loader({ request }: LoaderArgs) {
  const result = await getRandomJoke(
    null,
    await getUserId(request)
  )
  if (!result.success) {
    throw new Response('No jokes to be found!', { status: 404 })
  }
  return json(result.data)
}

Do you see a pattern emerging on those controllers?

If you want to see the full Jokes App implemented with `domain-functions` check this PR diff!.

Keeping a Pattern

With controllers doing so much, it is harder to keep a standard way to structure your successful and failed responses.

Should we be adding try/catch in our controllers?
How are we going to return input errors and how to differ 'em from actual runtime or service errors?

domain-functions does that for you, by having a structured way to present data and errors, you can be sure the responses will always be consistent. You also don't need to work with try/catch blocks, we can actually just throw errors in our domain functions, the same pattern Remix uses internally, so you can only write the happy path of your domain functions and throw errors to ensure type safety:

const getJoke = makeDomainFunction(z.object({ id: z.string().nonempty() }), userIdSchema)
  (async ({ id }, jokesterId) => {
    const joke = await db.joke.findOne({ where: { id, jokesterId } })
    if (!joke) throw new Error('Joke not found')
    return joke
  })

On the domain function above, if successful the response will look like this:

const result = {
  success: true,
  data: { id: 1, name: 'Joke name', content: 'Joke content' },
  inputErrors: [],
  environmentErrors: [],
  errors: [],
}

Otherwise it'll look like this:

const result = {
  success: false,
  inputErrors: [],
  environmentErrors: [],
  errors: [{ message: 'Joke not found' }],
}

Now that we reduced the boilerplate out of our actions/loaders and found an architectural pattern, it is easy to start creating our own little abstractions on top of them.

// app/lib/index.ts
function queryResponse<T>(result: T) {
  if (!response.success)
    throw new Response('Not found', { status: 404 })
  return json<T>(result.data)
}

// app/routes/jokes/$id.tsx
export async function loader({ params }: LoaderArgs) {
  return queryResponse(await getJoke(params))
}

Testing

Now imagine you need to thoroughly test that original code.

Currently, there's no easy way to do it, without kind of mocking the Router API. The solution usually lies in E2E testing.

We'd like to do unit and integration tests in our business logic, though. Now that our domain functions are just functions that receive data and return data, we can easily write them:

// Soon we'll be writing about how we set up our test database.
// For the sake of brevity, pretend there's already a DB with jokes
describe('getRandomJoke', () => {
  it('returns a joke for the given userId', async () => {
    const { user, jokes } = await setup()
    const result = await getRandomJoke(null, user.id)
    if (!result.success) throw new Error('No jokes to be found!')
    expect(jokes.map(({ id }) => id)).toInclude(result.data.id)
  })
})

If you ever tried to do such sort of testing on your Remix routes you are probably happy about what you've just seen.

Parsing structured data from Forms

Ok, this is not a Remix limitation but rather a "limitation" of the FormData API.
It is often useful to parse structured data from forms, for example, when you have nested forms or repeatable fields.

FormData can only work with flat structures and we need to know the structure of the data beforehand to know if we should call formData.get('myField') or formData.getAll('myField'). It arguably does not scale for complex forms.

By structured data I mean making the FormData from this form:

<form method="post">
  <input name="numbers[]" value="1" />
  <input name="numbers[]" value="2" />
  <input name="person[0][email]" value="john@doe.com" />
  <input name="person[0][password]" value="1234" />
  <button type="submit">
    Submit
  </button>
</form>

Be interpreted as this:

{
  "numbers": ["1", "2"],
  "person": [{ "email": "john@doe.com", "password": "1234" }]
}

Well, domain-functions leverages qs to do that conversion for you with inputFromForm:

import { inputFromForm } from 'domain-functions'

const result = await myDomainFunction(await inputFromForm(request))

The library exposes other utilities for doing that sort of job.

End-to-end Type Safety and composition

One of the biggest complaints about Remix (and NextJS) is the lack of end-to-end type safety.
Having to maintain the types by hand is boring and prone to errors. We wanted an experience as good as tRPC and now that our domain functions have knowledge of your domain's I/O we are in the same situation as tRPC as stated by its author:

As for output types—tRPC trusts the return type inferred from your resolver which is reasonable IMO. These types largely originate from sources (Prisma queries, etc) that provide trustworthy types.

BTW: Colin is also the author of Zod and a bunch of nice projects, we can't overstate how much we like his projects.

When working with domain-functions, you don't need to be writing types by hand as they are infered out of the domain functions. The following GIF shows the DX of this workflow:

Composition

When we started working on this project, we didn't realize we'd achieve such a good type safety nor did we planned to create a perfect arithmetic progression by always expressing the return of our Domain Functions as Promise<Result<MyData>>.

So when we were confronted with the problem of working with multiple domains in a single loader without changing our controller's architecture, the answer was right in front of us: creating functions to compose multiple Domain Functions, resulting in... a Domain Function!

So far we've created 3 functions enabling us to code like this:

import { all, map, pipe } from 'domain-functions'
import { a, b, c, d, e } from './my-domain-functions.server'

// Transform the successful data, ex:
// { success: true, data: "foo" } => { success: true, data: true }
const x = map(a, Boolean)
// Create a domain function that is a sequence of Domain Functions
// where the output of one is the input of the next
const y = pipe(x, b, c)
// Create a domain function that will run all the given domain functions
// in parallel with `Promise.all`
const getData = all(d, e, y)

export async function loader({ params }: LoaderArgs) {
  return queryResponse(await getData(params))
}

export default function Component() {
  const [
    dataForD, dataForE, dataForY
  ] = useLoaderData<typeof loader>()
  // ...
}

All that logic and our loader's boilerplate is untouched!

This other GIF showcases the DX for compositions:

Conclusion

We are pretty excited about this project and we hope you'll like it.
We've been battle-testing it and can't wait to see the feedback of the community.

If you felt lost about the examples above, check out the documentation and examples of domain-functions.

We are gonna be over the moon if it helps more teams to structure their projects and we are looking forward to your feedback/contributions.

Replace clsx, classnames or classcat with your own little helper

Gustavo (Guga) Guichard — Wed, 18 Aug 2021 21:30:32 +0000

Have you ever taken a break from programming, only to return and wrestle with package updates, outdated dependencies, or broken code? This issue often arises if your project heavily relies on a multitude of libraries and packages. In such instances, you might want to consider reducing the number of external imports your project utilizes.

We encountered this issue recently and perceived it as an opportunity to write a small helper utility that could replace a popular package.
Today, I'll be replacing a widely-used package called clsx (or classnames, etc) with a tiny function.

Planning

With clsx, you can pass a mix of strings, objects, arrays, and it consistently resolves to a string of classes to be used in your elements. If you're using a framework like Tailwind, where everything is accomplished through classes, you likely depend heavily on this function.

However, my colleagues and I rarely used it with objects.

Instead of this:

clsx('base', undefined, ['more', 'classes'], {
  'bg-red': hasError,
  'pointer-events-none': !isEnabled,
  'font-semibold': isTitle,
  'font-normal': !isTitle,
})

// Result: "base more classes bg-red font-normal"

We prefer an API like:

cx('base', undefined, ['more', 'classes'],
  hasError && 'bg-red',
  isEnabled || 'pointer-events-none',
  isTitle ? 'font-semibold' : 'font-normal'
)

// Result: "base more classes bg-red font-normal"

In fact, with the addition of the || operator, the final API proved to be even better suited for our needs.

The implementation

The final version of our function, which is just a few lines of code, accepts an array of unknown values, filters for strings, joins them with a space, and trims any leading or trailing whitespace:

function cx(...args: unknown[]) {
  return args
    .flat()
    .filter(x => typeof x === 'string')
    .join(' ')
    .trim()
}

Conclusion

Think twice before adding yet another package. Sometimes, all you need are a few lines of code - which might be fewer than the additions made to your package-lock.json at the end of the day. Always consider whether you can achieve the same functionality with a simpler, custom solution.

Forem: Gustavo (Guga) Guichard

Type-Safe Env Vars With Vite - A Modern Approach

The Gist of Changes

The New makeTypedEnvironment Helper

Accepting Different Parsers and Preventing Mutations

Transforming the Env Vars to camelCase

Getting rid of the VITE_ prefix

Last Optimization: Caching

Extending Schemas

Et Voilà

That's It

Update: make-typed-env on npm

Using Arktype in Place of Zod - How to Adapt Parsers

A newfound love

The libraries I'm adapting for

make-service

composable-functions

The difference between the libraries

TDD: Type Driven Development 😄

The implementation

Usage

Final thoughts

Enforcing 'noImplicitAny' on callbacks to generic functions

The problem

The quest

The solution

Conclusion

Why you should use Remix Full-Stack: Improved Productivity and Collaboration

TLDR

Rails: The Good Ol' Days

Our Business Problem with SPAs

Our Urge for a New Stack

You Might Not Get the Full Potential of Remix

Remix Opened the Door to the Back-end World

Conclusion

Type-safe environment variables on both client and server with Remix

Baseline

Type-safe process.env

Type-safe window.ENV

The <PublicEnv /> component

Universal environment variables

Final touches

That's it 🔥

Check the repo on github

Creating a Github-like Progress bar for your Remix app

This is a follow-up post

Intro

Start by styling it properly

Introducing navigation.state

I wish there was the 4th step

Ok, how are we gonna do this?

Understanding the important parts

The final code

Add a Global Progress indicator to your Remix app

Disclaimer: there's a follow-up post for this one

Intro

Got it, show me the code!

Preparation

The GlobalLoading component

The Spinner

The active state

aria-* stuff

The Tailwind classes

Et voilá

We can dive deeper

How domain-functions improves the (already awesome) DX of Remix projects?

Plumbing

So how would we decouple that business logic with domain-functions?

If you want to see the full Jokes App implemented with domain-functions check this PR diff!.

Keeping a Pattern

Testing

Parsing structured data from Forms

End-to-end Type Safety and composition

Composition

Conclusion

Replace clsx, classnames or classcat with your own little helper

Planning

The implementation

Conclusion

The New `makeTypedEnvironment` Helper

Transforming the Env Vars to `camelCase`

Getting rid of the `VITE_` prefix

Update: `make-typed-env` on npm

The `<PublicEnv />` component

Introducing `navigation.state`

The `active` state

`aria-*` stuff

So how would we decouple that business logic with `domain-functions`?

If you want to see the full Jokes App implemented with `domain-functions` check this PR diff!.