DEV Community: Thorr ⚡️ codinsonn.dev

Zod and the Joy of Single Sources of Truth

Thorr ⚡️ codinsonn.dev — Wed, 29 May 2024 10:33:19 +0000

If you love Typescript and haven't been living under a rock for the past 2 years, you've likely heard of Zod.

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

Zod is a Typescript-first schema validation library, aimed at maximum TS compatibility. It powers popular libraries like TRPC & has a big ecosystem around it

An important design goal is to provide type safety at runtime, not just build time.

The major strength of Zod is that it can extract types from your validation schema. For example, this is how you would define primitive data validators in Zod and extract the types

import { z } from 'zod'

// - Strings -

const StringValue = z.string()
type StringValue = z.infer<typeof StringValue> // => string

StringValue.parse("Hello World") // => ✅ inferred result = string
StringValue.parse(42) // => throws ZodError at runtime

Here's what it would look like for other primitive types:

// - Numbers -

const NumberValue = z.number()
type NumberValue = z.infer<typeof NumberValue> // => number

NumberValue.parse(42) // => ✅ inferred type = number
NumberValue.parse("15") // => throws ZodError at runtime

// - Booleans -

const BooleanValue = z.boolean()
type BooleanValue = z.infer<typeof BooleanValue> // => boolean

BooleanValue.parse(true) // => ✅ type = boolean
BooleanValue.parse("false") // => ZodError

// - Dates -

const DateValue = z.date()
type DateValue = z.infer<typeof DateValue> // => Date

DateValue.parse(new Date()) // => ✅ type = Date
DateValue.parse("Next Friday") // also throws

Already, Zod acts as a 'single source of truth' for validation and types.

To understand the power of Zod, you need to think of it as a single source of truth for your data structures:

// This is just a type
type SomeDatastructure = {
    name: string
    age: number
    isStudent: boolean
    birthdate: Date
}

// This provides both types AND validation
// + it can never get out of sync ✅
const SomeDatastructureSchema = z.object({
    name: z.string(),
    age: z.number(),
    isStudent: z.boolean(),
    birthdate: z.date()
})

In this article, I'll build up to more advanced use cases of Zod, and how it can be used as a single source of truth for not just types and validation, but any datastructure definition in your entire codebase.

Convert with Type Coercion

Sometimes, you don't want things like "42" to be rejected when you're expecting a number.

You want to convert them to the correct type instead:

const NumberValue = z.coerce.number() // <= Prefix with .coerce to enable type coercion
const someNumber = NumberValue.parse("42") // => 42

From the zod.dev docs:

"During the parsing step, the input is passed through the String() function,

which is a JavaScript built-in for coercing data into strings."

You can do this for any primitive data type:

const StringValue = z.coerce.string() // When parsing -> String(input)
const someString = StringValue.parse(42) // => "42"

const DateValue = z.coerce.date() // -> new Date(input)
const someDate = DateValue.parse("2024-05-29") // => Date (Wed May 29 2024 00:00:00 GMT+0200)

const BooleanValue = z.coerce.boolean() // -> Boolean(input)
const someBoolean = BooleanValue.parse(0) // => false (falsy value)

// -!- Caveat: strings are technically truthy
const anotherBoolean = BooleanValue.parse("false") // => true

Validation Errors

So let's look at what happens when you try to parse invalid data:

try {
    const someNumber = z.number().parse("This is not a number")
} catch (err) {
    /* Throws 'ZodError' with a .issues array:
        [ {
            code: 'invalid_type',
            expected: 'number',
            received: 'string',
            path: [],
            message: 'Expected string, received number',
        } ]
    */
}

From the zod.dev docs:

All validation errors thrown by Zod are instances of ZodError.

ZodError is a subclass of Error; you can create your own instance easily:

import * as z from "zod";

const MyCustomError = new z.ZodError([]);

Each ZodError has an issues property that is an array of ZodIssues.

Each issue documents a problem that occurred during validation.

But, customizing error messages is easier than you might think:

Custom Error Messages

const NumberValue = z.number({ message: "Please provide a number" })
// => Throws ZodError [{ message: "Please provide a number", code: ... }]

const MinimumValue = z.number().min(10, { message: "Value must be at least 10" })
// => Throws ZodError [{ message: "Value must be at least 10", code: ... }]

const MaximumValue = z.number().max(100, { message: "Value must be at most 100" })
// => Throws ZodError [{ message: "Value must be at most 100", code: ... }]

Going beyond TS by narrowing types

The .min() and .max() methods on ZodNumber from the previous examples are just the tip of the iceberg. They're a great example of what's possible beyond typescript-like type validation and narrowing.

For example, you can also use .min(), .max() and even .length() on strings and arrays:

// e.g. TS can't enforce a minimum length (👇) on a string
const CountryNameValidator = z.string().min(4, { 
    message: "Country name must be at least 4 characters long"
})

// ... or an exact length on an array (👇) *
const PointValue3D = z.array(z.number()).length(3, {
    message: "Coördinate must have x, y, z values"
})

*Though you could probably hack it together with Tuples 🤔

Advanced Types: Enums, Tuples and more

Speaking of, more advanced types like Tuples or Enums are also supported by Zod:

const PointValue2D = z.tuple([z.number(), z.number()]) // => [number, number]

const Direction = z.enum(["Left", "Right"]) // => "Left" | "Right"

Alternatively, for enums, you could provide an actual enum:

enum DirectionEnum {
    Left = "Left",
    Right = "Right"
}

const Direction = z.enum(DirectionEnum) // => DirectionEnum

If you want to use a zod enum to autocomplete options from, you can:

const Languages = z.enum(["PHP", "Ruby", "Typescript", "Python"])
type Languages = z.infer<typeof Languages>
// => "PHP" | "Ruby" | "Typescript" | "Python"

// You can use .enum for a native-like (👇) experience to pick options
const myFavoriteLanguage = Languages.enum.TypeScript // => "Typescript"

// ... which is the equivalent of:

enum Languages {
    PHP = "PHP",
    Ruby = "Ruby",
    TypeScript = "Typescript",
    Python = "Python"
}

const myFavoriteLanguage = Languages.TypeScript // => "Typescript"

There's more:

Zod also supports more advanced types like union(), intersection(), promise(), lazy(), nullable(), optional(), array(), object(), record(), map(), set(), function(), instanceof(), promise() and unknown().

However, if you're interested in learning the ins and outs, I highly recommend checking out the awesome Zod documentation, after you've read this article.

I won't go into further detail on these, as this is not just about Zod and how to use it.

It's about using schemas as single sources of truth.

Bringing it together in Schemas

Validating individual fields is great, but typically, you'll want to validate entire objects.

You can easily do this with z.object():

const User = z.object({
    name: z.string(),
    age: z.number(),
    isStudent: z.boolean(),
    birthdate: z.date()
})

Here too, the aliased schema type can be used for editor hints or instant feedback:

// Alias the Schema to the inferred type
type User = z.infer<typeof User> // <- Common pattern

const someUser: User = {
    name: "John Doe",
    age: 42,
    isStudent: false,
    birthdate: new Date("1980-01-01")
}

// => ✅ Yup, that satisfies the `User` type

Just like in Typescript, if you want to derive another user type from the User schema, you can:

// Extend the User schema
const Admin = User.extend({
    isAdmin: z.boolean()
})

type Admin = z.infer<typeof Admin>
// => { name: string, age: number, isStudent: boolean, birthdate: Date, isAdmin: boolean }

Other supported methods are pick() and omit():

// Omit fields from the User schema
const PublicUser = User.omit({ birthdate: true })

type PublicUser = z.infer<typeof PublicUser>
// => { name: string, age: number, isStudent: boolean }

// Pick fields from the User schema
const MinimalUser = User.pick({ name: true, age: true })

type MinimalUser = z.infer<typeof MinimalUser>
// => { name: string, age: number }

Need to represent a collection of users...?

// Use a z.array() with the 'User' schema
const Team = z.object({
    members: z.array(User) // <- Reusing the 'User' schema
    teamName: z.string(),
})

type Team = z.infer<typeof Team>
// => { teamName: string, members: User[] }

... or maybe you want a lookup object?

// Use a z.record() for datastructure to e.g. to look up users by their ID
const UserLookup = z.record(z.string(), User)
// where z.string() is the type of the id

type UserLookup = z.infer<typeof UserLookup>
// => { [key: string]: User }

It's no understatement to say that Zod is already a powerful tool for defining data structures in your codebase.

But it can be so much more than that.

Why single sources of truth?

Think of all the places you might need to repeat certain field definitions:

✅ Types
✅ Validation
✅ Database Models
✅ API Inputs & Responses
✅ Form State
✅ Documentation
✅ Mocks & Test Data
✅ GraphQL schema & query definitions

Now think about how much time you spend to keep all of these in sync.

Not to mention the cognitive overhead of having to remember all the different places where you've defined the same thing.

I've personally torn my hair out over this a few times. I'd updated the types, input validation, edited my back-end code, the database model and the form, but forgot to update a GraphQL query and schema.

It can be a nightmare.

Now think of what it would be like if you could define your data structures in one place.

And have everything else derive from that.

Ecosystem Shoutouts

This is where the Zod ecosystem comes in:

Need to build APIs from zod schemas? 🤔

tRPC: end-to-end typesafe APIs without GraphQL.
@anatine/zod-nestjs: using Zod in a NestJS project.

Need to integrate zod schemas within your form library? 🤔

react-hook-form: Zod resolver for React Hook Form.
zod-formik-adapter: Formik adapter for Zod.

Need to transform zod schemas into other formats? 🤔

zod-to-json-schema: Convert Zod schemas into JSON Schemas.
@anatine/zod-openapi: Converts Zod schema to OpenAPI v3.x SchemaObject.
nestjs-graphql-zod: Generates NestJS GraphQL model

Disclaimer: For each example here, there are at least 4 to 5 more tools and libraries in the Zod ecosystem to choose from.

✅ Using just the ecosystem alone, you could already use Zod as a single source of truth for any data structure in your codebase.

🤔 The problem is that it is quite fragmented. Between these different installable tools, there are also different opinions on what an ideal API around it should look like.

Sometimes, the best code is the code you own yourself. Which is what I've been experimenting with:

What makes a good Single Source of Truth?

Let's think about it.

What essential metadata should be derivable from a single source of truth?

type IdealSourceOfTruth<T = unknown> = {

  // -i- We need some basis to map to other formats
  baseType: 'String' | 'Boolean' | ... | 'Object' | 'Array' | ...,
  zodType: 'ZodString' | 'ZodBoolean' | ... | 'ZodObject' | ...,

  // -i- We should keep track of optionality
  isOptional?: boolean,
  isNullable?: boolean,
  defaultValue?: T,

  // -i- Ideally, for documentation & e.g. GraphQL codegen
  name?: string,
  exampleValue?: T,
  description?: string,

  // -i- If specified...
  minValue?: number,
  maxValue?: number,
  exactLength?: number,
  regexPattern?: RegExp,

  // -i- We should support nested introspection
  // -i- For e.g. enums, arrays, objects, records, ...
  schema?: Record<string, IdealSourceOfTruth> | IdealSourceOfTruth[]
  // 👆 which would depend on the main `zodType`

}

Introspection & Metadata

What's missing in Zod?

At the core of a good single source of truth is a good introspection API:

Introspection is the ability to examine the structure of a schema at runtime to extract all relevant metadata from it and its fields.

Sadly, Zod doesn't have this out of the box.

There's actually a bunch of issues asking for it:

It seems like people really want a strong introspection API in Zod to build their own custom stuff around.

But what if it did have it?

Turns out, adding introspection to Zod in a way that feels native to it is not super hard:

Adding Introspection to Zod

All it takes is some light additions to the Zod interface:

Note: Editing the prototype of anything is typically dangerous and could lead to bugs or unexpected behavior. While we opted to do it to make it feel native to Zod, it's best to only use it for additions (in moderation), but NEVER modifications.

schemas.ts

import { z, ZodObject, ZodType } from 'zod'

/* --- Zod type extensions ----------------------------- */

declare module 'zod' {

    // -i- Add metadata, example and introspection methods to the ZodObject type
    interface ZodType {
        metadata(): Record<string, any>, // <-- Retrieve metadata from a Zod type
        addMeta(meta: Record<string, any>): this // <- Add metadata to a Zod type
        example<T extends this['_type']>(exampleValue: T): this // <- Add an example value
        introspect(): Metadata & Record<string, any> // <- Introspect a Zod type
    }

    // -i- Make sure we can name and rename Zod schemas
    interface ZodObject<...> {
        nameSchema(name: string): this // <- Name a Zod schema
        extendSchema(name: string, shape: S): this // <- Extend a Zod schema & rename it
        pickSchema(name: string, keys: Record<keyof S, boolean>): this // <- Pick & rename
        omitSchema(name: string, keys: Record<keyof S, boolean>): this // <- Omit & rename
    }

}

/* --- Zod prototype extensions ------------------------ */

// ... Actual implementation of the added methods, omitted for brevity ...

To check out the full implementation, see the full code on GitHub:

FullProduct.dev - @green-stack/core - schemas on Github

Using our custom introspection API

On that note, let's create a custom schema() function in our custom schemas.ts file to allow naming and describing single sources of truth without editing the z.object() constructor directly:

// -i- To be used to create the initial schema
export const schema = <S extends z.ZodRawShape>(name: string, shape: S) => {
    return z.object(shape).nameSchema(name)
}

// -i- Reexport `z` so the user can opt in / out to prototype extensions
// -i- ...depending on where they import from
export { z } from 'zod'

Which will allows us to do things like:

// -i- Opt into the introspection API by importing from our own `schemas.ts` file
import { z, schema } from './schemas'

// -i- Create a single source of truth by using the custom `schema()` function we made 
const User = schema('User', {
    name: z.string().example("John Doe"),
    age: z.number().addMeta({ someKey: "Some introspection data" }),
    birthdate: z.date().describe("The user's birthdate")
})

// -i- Alias the inferred type so you only need 1 import
type User = z.infer<typeof User>

To then retrieve all metadata from the schema:

const userDefinition = User.introspect()

This resulting object is a JS object, but could be stringified to JSON if required:

{
    "name": "User",
    "zodType": "ZodObject", // <- The actual Zod Class used
    "baseType": "Object",
    "schema": {
        "name": {
            "zodType": "ZodString",
            "baseType": "String", // <- To transform to other formats
            "exampleValue": "John Doe"
        },
        "age": {
            "zodType": "ZodNumber",
            "baseType": "Number",
            "exampleValue": 42, // <- Good for docs
            "someKey": "Some metadata" // <- Custom meta
        },
        "birthdate": {
            "zodType": "ZodDate",
            "baseType": "Date",
            "description": "The user's birthdate" // <- Good for docs
        }
    }
}

Later we'll look at how we can use this metadata to generate other things like documentation, mocks, database models, etc.

Optionality and Defaults

Zod has native support for things like .nullable(), .optional() and .default().

Ideally, we'd be able to derive this information in introspection as well.

// Define a schema with optional and nullable fields
const User = schema('User', {
    name: z.string().optional(), // <- Allow `undefined`
    age: z.number().nullable(), // <- Allow `null`
    birthdate: z.date().nullish(), // <- Allow `null` & `undefined`
    isAdmin: z.boolean().default(false) // <- Allow `undefined` + use `false` if missing
})

This is actually one of the things that make adding a proper introspection API a bit difficult, since Zod wraps it's internal classes in some layers of abstraction:

// e.g. A nullish field with defaults might look like this:
ZodDefault(
    ZodNullable(
        ZodOptional(
            ZodString(/* ... */)
        )
    )
)

You'd typically need to do some recursive layer unwrapping to get to the actual field definition of ZodString in this case.

Luckily, our custom introspect() method is set up to handle this for us and flattens the resulting metadata object into a more easily digestible format:

{
    "name": "User",
    "zodType": "ZodObject",
    "baseType": "Object",
    "schema": {
        "name": {
            "zodType": "ZodString",
            "baseType": "String",
            // 👇 As we wanted for our ideal Single Source of Truth
            "isOptional": true
        },
        "age": {
            "zodType": "ZodNumber",
            "baseType": "Number",
            // 👇 As we wanted for our ideal Single Source of Truth
            "isNullable": true
        },
        "birthdate": {
            "zodType": "ZodDate",
            "baseType": "Date",
            // 👇 Both optional and nullable due to `.nullish()`
            "isOptional": true, 
            "isNullable": true
        },
        "isAdmin": {
            "zodType": "ZodBoolean",
            "baseType": "Boolean",
            "isOptional": true,
            // 👇 Also keeps track of the default value
            "defaultValue": false
        }
    }
}

Now that we can extract metadata (optionality, defaults, examples, types, etc.) from our schemas, we can use these introspection results to generate other things.

Single Source of Truth Examples

Designing Database Models with Zod

For example, you want to generate a database model from your Zod schema.

You could build and apply a transformer function that takes the introspection result and generates a Mongoose model from it:

schemaToMongoose.ts

// Conceptual transformer function
import { z, createSchemaPlugin } from '@green-stack/schemas'
// Import mongoose specific stuff
import mongoose, { Schema, Model, Document, ... } from 'mongoose'

// --------------------------------------------------------
// -i- Conceptual meta/example code, not actual code
// --------------------------------------------------------

// Take a schema as input, infer its type for later use
export const schemaToMongoose = <S extends z.ZodRawShape>(schema: z.ZodObject<S>) => {

    // Create a field builder for metadata aside from the base type
    const createMongooseField = (mongooseType) => {

        // Return a function that builds a Mongoose field from introspection data
        return (fieldKey, fieldMeta) => {

            // Build the base definition
            const mongooseField = {
                type: mongooseType,
                required: !fieldMeta.isOptional && !fieldMeta.isNullable,
                default: fieldMeta.defaultValue,
                description: fieldMeta.description
            }

            // Handle special cases like enums
            if (fieldMeta.zodType === 'ZodEnum') {
                mongooseField.enum = Object.values(schemaConfig.schema)
            }

            // Return the Mongoose field definition
            return mongooseField

        }

    }

    // Build the mongoose schema definition by mapping metadata to Mongoose fields
    const mongooseSchemaDef = createSchemaPlugin(
        // Feed it the schema metadata from introspection
        schema.introspect(),
        // Map Zod types to Mongoose types
        {
            String: createMongooseField(String),
            Number: createMongooseField(Number),
            Date: createMongooseField(Date),
            Boolean: createMongooseField(Boolean),
            Enum: createMongooseField(String)
            // ... other zod types ...
        },
    )

    // Create mongoose Schema from SchemaDefinition
    type SchemaDoc = Document & z.infer<z.ZodObject<S>> // <- Infer the schema type
    const mongooseSchema: Schema<SchemaDoc> = new Schema(mongooseSchemaDefinition)

    // Build & return the mongoose model
    const schemaModel = model<SchemaDoc>(schema.schemaName, mongooseSchema) as SchemaModel
    return schemaModel
}

Note: This is a conceptual example. The actual implementation would be a bit (but not much) more complex and handle more edge cases. I'll link you my actual implementations at the end.

To build a Mongoose model from a Zod schema, you'd use it like this:

// Import the schema and the transformer function
import { User } from './schemas'
import { schemaToMongoose } from './schemaToMongoose'

// Generate the Mongoose model from the Zod schema
const UserModel = schemaToMongoose(User) // <- Typed Mongoose model with `User` type

// Use the Mongoose model as you would any other
// It will apply & enforce the types inferred from the Zod schema
const user = new UserModel({
    name: "John Doe",
    age: 44,
    birthdate: new Date("1980-01-01")
})

You could apply the same principle to generate other database modeling tools or ORMs like Prisma, TypeORM, Drizzle etc.

Build a transformer function that takes in a schema
Use introspection to extract metadata from the schema
Map the metadata to some other structure (like a DB schema)
Build the full database model from the transformed fields
Assign the types inferred from the Zod schema to the database model

Now, if you need to change your database model, you only need to change the Zod schema. Typescript will automatically catch any errors in your codebase that need to be updated.

Pretty powerful, right?

Generating Docs

Many don't feel they have the time to write good documentation, even though they might see it as important.

What if you could attach the same Zod schema your React components use for types to generate docs from?

You'd need to parse the schema metadata and generate a markdown table or something like Storybook controls from it:

schemaToStorybookDocs.ts

import { z, schema } from '@green-stack/schemas'

/* --- Prop Schema ----------------- */

const GreetingProps = schema('GreetingProps', {
    name: z.string().example("John"),
})

/* --- <Greeting /> ---------------- */

// -i- React component that uses the schema's type inference
export const Greeting = ({ name }: z.infer<typeof GreetingProps>) => (
    <h1>Welcome back, {name}! 👋</h1>
)

/* --- Documentation --------------- */

// -i- Export the schema for Storybook to use
export const docSchema = GreetingProps

Note: You'll need some node script to scan your codebase with e.g. glob and build .stories.mdx files for you though. In those generated markdown files, you'll map

schemaToStorybookDocs.ts

// Similiar to the Mongoose example, but for Storybook controls
import { z, createSchemaPlugin } from '@green-stack/schemas'

/* --- schemaToStorybookDocs() ----- */

export const schemaToStorybookDocs = <S extends z.ZodRawShape>(schema: z.ZodObject<S>) => {

    // ... Similar conceptual code to the Mongoose example ...
    const createStorybookControl = (dataType, controlType) => (fieldKey, fieldMeta) => {
        // ... Do stuff with metadata: defaultValue, exampleValue, isOptional, enum options etc ...
    }

    // Build the Storybook controls definition by mapping metadata to Storybook controls
    const storybookControls = createSchemaPlugin(schema.introspect(),
        {
            // Map baseTypes to Storybook data (👇) & control (👇) types
            Boolean: createStorybookControl('boolean', 'boolean'),
            String: createStorybookControl('string', 'text'),
            Number: createStorybookControl('number', 'number'),
            Date: createStorybookControl('date', 'date'),
            Enum: createStorybookControl('enum', 'select'), // <- e.g. Use a select dropdown for enums
            // ... other zod types ...
        },
    )

    // Return the Storybook controls
    return storybookControls
}

Which, after codegen creates a .stories.mdx file that uses schemaToStorybookDocs(), might look something like this:

Demo: You can test out a full working example of Zod-powered Storybook docs here: codinsonn.dev fully generated Storybook docs (+ Github Source)

Resolvers and Databridges

My favorite example of building stuff around schemas is a concept I've dubbed a DataBridge

You can think of a DataBridge as a way to bundle the metadata around a resolver function with the Zod schemas of its input and output.

For example, if we have a resolver function that works in both REST or GraphQL :

healthCheck.bridge.ts

import { z, schema } from '@green-stack/core/schemas'
import { createDataBridge } from '@green-stack/core/schemas/createDataBridge'

/* --- Schemas ----------------------------------------- */

export const HealthCheckArgs = schema('HealthCheckArgs', {
    echo: z.string().describe("Echoes back the echo argument")
})

// Since we reuse the "echo" arg in the response, we can extend (👇) from the input schema
export const HealthCheckResponse = HealthCheckArgs.extendSchema('HealthCheckResponse', {
    alive: z.boolean().default(true),
    kicking: z.boolean().default(true),
})

/* --- Types ------------------------------------------- */

export type HealthCheckArgs = z.infer<typeof HealthCheckArgs>

export type HealthCheckResponse = z.infer<typeof HealthCheckResponse>

/* --- DataBridge -------------------------------------- */

export const healthCheckBridge = createDataBridge({
    // Bundles the input & output schemas with the resolver metadata
    argsSchema: HealthCheckArgs,
    responseSchema: HealthCheckResponse,
    // API route metadata
    apiPath: '/api/health',
    allowedMethods: ['GET', 'POST', 'GRAPHQL'],
    // GraphQL metadata
    resolverName: 'healthCheck',
})

You might wonder why we're defining this in a file that's separate from the actual resolver function.

The reason is that we can reuse this DataBridge on both the client and server side.

On the server side, image a wrapper createResolver() function that takes a function implementation as a first argument and the DataBridge as a second:

healthCheck.resolver.ts

// Helper function that integrates the resolver with the DataBridge
import { createResolver } from '@green-stack/core'

// Import the DataBridge we defined earlier
import { healthCheckBridge } from './healthCheck.bridge'

/* --- healthCheck() ----------------------------------- */

export const healthCheck = createResolver(({ args, parseArgs, withDefaults }) => {
    //                               Handy helpers (☝️) from the DataBridge

    // Typesafe Args from Databridge Input schema
    const { echo } = args // <- { echo?: string }
    // -- OR --
    const { echo } = parseArgs() // <- { echo?: string }

    // Check type match from the Databridge Output schema & apply defaults
    return withDefaults({
        echo,
        alive: "", // <- Caught by Typescript, will have red squiggly line
        kicking: undefined, // <- Defaults to `true`
    })

}, healthCheckBridge)
// ☝️ Pass the DataBridge as the second argument to power types & resolver utils

Congrats. On the server side, you now have a fully typed resolver function that's bundled together with schemas of its input and output.

On the client, you could use just the DataBridge to build a REST fetcher or even build a GraphQL query from the bridge object, without conflicting with the server-side code.

While on the server, you could use the portable resolver bundle to generate your executable GraphQL schema from. Automagically.

Let's have a look at how that might be achieved.

Zod for simplifying GraphQL

Who thinks GraphQL is too complicated? 🙋‍♂

Let's bring our healthCheck resolver to GraphQL. We'll need to:

Generate GraphQL schema definitions from the healthCheckBridge
Generate a GraphQL query to call the healthCheckBridge query from the front-end

Again, we'll combine the introspection API for the DataBridge with a transformer function to generate the GraphQL schema and query:

bridgeToSchema.ts

// Similiar to the Mongoose & Docs example, but for a GraphQL-schema
import { z, createSchemaPlugin } from '@green-stack/core/schemas'

// ...

// -i- We'll need to run this for both the Args & Response schemas individually
const storybookControls = createSchemaPlugin(schema.introspect(),
    {
        // Map baseTypes to GraphQL-schema definitions
        Boolean: createSchemaField('Boolean'),
        String: createSchemaField('String'),
        Number: createSchemaField('Float'), // <- e.g. Float! or Float
        Date: createSchemaField('Date'), // <- e.g. Date! or Date (scalar)
        Enum: createSchemaField('String'), // <- e.g. String! or String
        // ... other zod types ...
        Object: createSchemaField(field.schemaName) // <- Will need some recursion magic for nested schemas
    },
)

Once applied and loaded into your GraphQL server, if your mapper function is set up correctly, you should be able to propagate even your descriptions from z.{someType}.describe('...') to your GraphQL schema:

We now no longer need to maintain separate GraphQL schema definitions.

It's all derived from the Zod args and response schemas in the resolver's DataBridge.

With a bit of creativity, we could even generate the GraphQL query to call the healthCheck resolver from the front-end:

healthCheck.query.ts

// -i- Like types & schemas, we can import & reuse the bridge client-side
import { healthCheckBridge } from './healthCheck.bridge'
import { renderBridgeToQuery } from '@green-stack/schemas'

// -i- Generate a GraphQL query from the DataBridge
const healthCheckQuery = renderBridgeToQuery(healthCheckBridge)

/* -i- Resulting in the following query string:

    `query($args: HealthCheckArgs) {
        healthCheck(args: $args) {
            echo
            alive
            kicking
        }
    }`
*/

Which you could then use to build a typed fetcher function:

healthCheck.fetcher.ts

const healthCheckFetcher = (args: z.infer<typeof healthCheckBridge.argsSchema>) => {
    // -i- Fetch the query with the args (inferred from the schema ☝️)

    const res = await fetch('/api/graphql', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            // ...headers,
        },
        body: JSON.stringify({
            query: healthCheckQuery,
            variables
        }),
    })

    // -i- Return the response (which you can type from the response schema 👇)
    return res.data.healthCheck as z.infer<typeof healthCheckBridge.responseSchema>
}

In the end, you get all the benefits of GraphQL while avoiding most extra boilerplate steps involved in maintaining it

Scaffolding Forms?

As a final example, many only think of validation libraries like Zod for integrating them with their forms.

But what if you could scaffold your forms from your Zod schemas on top?

UserRegistrationForm.tsx

return (
    <SchemaForm
        schema={User}

        /* With single sources of truth, */
        /* ...what's stopping you from coding like this? */

        schemaToInputs={{
            String: (fieldMeta) => <input type="text" {...fieldMeta} />,
            Number: (fieldMeta) => <input type="number" {...fieldMeta} />,
            Date: (fieldMeta) => <input type="date" {...fieldMeta} />,
            Boolean: (fieldMeta) => <input type="checkbox" {...fieldMeta} />,
            Enum: (fieldMeta) => <select {...fieldMeta}>
        }}
    />
)

Even better DX with Codegen

All of this might still seem like a lot of manual linking between:

Zod schemas
Databridges & Resolvers
Forms, Hooks, Components, Docs, APIs, Fetchers, etc.

But even this can be automated with cli tools if you want it to be:

>>> Modify "your-codebase" using turborepo generators?

? Where would you like to add this schema? # -> @app/core/schemas
? What will you name the schema? (e.g. "User") # -> UserSchema
? Optional description: What will this schema be used for? # -> Keep track of user data
? What would you like to generate linked to this resolver?

> ✅ Database Model (Mongoose)
> ✅ Databridge & Resolver shell
> ✅ GraphQL Query / Mutation
> ✅ GET / POST / PUT / DELETE API routes
> ✅ Typed fetcher function
> ✅ Typed `formState` hook
> ✅ Component Docs

The sweet thing is, you don't need to build this all from scratch anymore...

While there's no NPM package for this, where can you test working with Single Sources of Truth?

FullProduct.dev ⚡️ Universal App Starterkit

I've been working on a project called FullProduct.dev to provide a full-stack starterkit for building modern Universal Apps. Single sources of truth are a big part of that.

Like most time-saving templates, it will set you up with:

Authentication
Payments
Email
Scalable Back-end
Essential UI components

❌ But those other boilerplates are usually just for the web, and often don't have extensive docs or an optional recommended way of working that comes with them.

🤔 You also often don't get to test the template before you buy it, and might still have to spend time switching out parts you don't like with ones you're used to.

Why FullProduct.dev ⚡️ ?

✅ Universal from the start - Bridges gap between Expo & Next.js

✅ Write-once UI - Combines NativeWind & React Native Web for consistent look & feel on each device

✅ Recommended way of working - based on Schemas, DataBridges & Single Sources of Truth

✅ Docs and Docgen - Documentation that grows with you as you continue to build with schemas

✅ Built for Copy-Paste - Our way of working enables you to copy-paste full features between projects

✅ Customizable - Pick and choose from inspectable & diffable git-based plugins

While FullProduct.dev is still in active development, scheduled for a Product Hunt release in September 2024, you can already explore its core concepts in the source-available free demo or the previous iteration:

FullProduct.dev GREEN stack starter - Previous iteration of FullProduct.dev (docs)
Universal Base Starter - Base FullProduct.dev starterkit, with plugin PRs (docs)

The full working versions of the pseudo-code examples can also be found in these template repos:

To get started with them, use the Github UI to fork it and include all branches

If you want to check what our git-based plugins might feel like:

Liked this article? 💚

Want to get regular updates on the FullProduct.dev ⚡️ project?

Or learn more about single sources of truth, data bridges or Zod?

You can find the links to the source code / blog / socials on codinsonn.dev ⚡️

Thank you for reading, hope you found it inspirational! 🙏

React-Native over Flutter? - How to choose cross-platform tech

Thorr ⚡️ codinsonn.dev — Thu, 24 Aug 2023 16:04:26 +0000

Users increasingly prefer mobile apps to the mobile web, and there are many ways to build them.

Recently, 'VeryGoodVentures' (a Flutter Consultancy Company) released a whitepaper detailing stats on the impact of adaptating Flutter.

One very true take the Whitepaper starts with is that:

Which, ofcourse, sparked the age old debate of what cross-platform technology is best to start with. A discussion where the main options are the usual suspects of Flutter, React-Native and web wrappers like Cordova/Ionic/Capacitor.

This blogpost examines when each of these solutions tends to make sense. As with most tech choices, the answer is "It depends"

Misleading stats?

You might notice that in their promotional material of their whitepaper, the graph they share comparing Flutter to React-Native looks kind of funky:

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

React-Native is at 42% in the top left corner
at the same elevation in the opposite corner it states 46%?
in the middle, it also states 42% (??)

On top of that, other sources say that it is actually pretty hard to find a job in Flutter these days. Which would contradict some of the statements made in the whitepaper and the graph they chose to share.

These could ofcourse just be design mistakes. But, let's have a look at some important, easily verifyable numbers instead:

What the App Stores say

Expo-Router maintainer @evanbacon (@baconbrix on Twitter) does a great job comparing what tech is used under the hood in the top 100 apps of various app store categories:

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

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

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

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

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

From these app store comparisons, you could conclude the following things:

Percentage wise, a lot of the top 100 apps in any category still seem to be built with either native tech (like Swift or Kotlin) or a bit more outdated native adjacent interface builders
React-Native is a close second, with pretty good ratings overall
Flutter & Web wrappers are definitely represented, but not nearly as much as React-Native and Native are.

But, is this really a fair comparison? Do these categories cover all the areas and types of apps where you could consider Flutter?

So when does Flutter make sense?

Where Flutter really shines is when animation and graphics performance matters a lot.

So, if we were to instead compare the top 100 image / video editing tools or top 100 gaming apps, I would not be surprised if Flutter took more of a lead there. (Where react-native and web wrappers are probably not even represented at all)

The reasons are as follows:

How to choose cross-platform tech?

In one of his recent videos, twitch streamer and open-source maintainer Theo Browne (@t3dotgg) came up with a pretty good decision framework for when to choose which tech for the solution your app solves:

When examining which tech stack to use for mobile dev, consider the choices based on:

How much animation your app will need (Y axis)
How many native features the app needs (X axis)

And choose + hire accordingly.

For example:

Knowing this, you should choose Flutter if:

✅ You have considered using an actual game engine instead
✅ You're building a heavily gamified app (e.g. for kids to learn stuff in)
✅ You're building an editing tool like the next Canva or Figma
✅ You know upfront that web won't need any SSR or SEO

Which would correspond pretty well with the pink line from Theo's video.

(PS: I highly recommend watching the entire video and Theo's other ones on this topic as well)

Though a canvas-based implementation in Flutter Web typically hinders its usefulness in terms of SEO, it * has * proven to be a great asset in web-only tools like CHILI Publish, where the surrounding UI is largely made in React, but the core image & animation editing features are fully built in Flutter for Web.

When web, SEO & SSR make sense

The best way to get free organic traffic to your solution is still by building a website or even a web version of your app.

Even in the age of AI, people still search for solutions to their problems in search engines like Google.

Make sure you're in their search results.

Which is not to say that you should * only * build a website or webapp. Because research also shows that users increasingly prefer mobile apps when they're already hooked on your solution.

So, in essence, web for discovery, and mobile apps for conversions and reach. You'll likely need both.

One way you could achieve that easily is by using web-wrappers like Cordova/Ionic/Capacitor.

According to the tech decision framework, here's when that works best:

When might one use web wrappers for mobile?

✅ You want a native-like experience with just web-tech
✅ ... but the results don't need to be an actual native app
✅ Team knows only non React JS frameworks like Vue or Svelte
✅ e.g. You're building an eCommerce store, a blogging platform (SEO)

It's also important to know that like with React-Native, tools like Capacitor can actually help you implement integrations with actual native features and even custom native code should you want to.

While with React-Native, this can also go both ways.

When to use tools like React-Native and Expo?

✅ You want an actual native experience using JS & React
✅ You might need to implement native code at some point
✅ Team already knows React and wants to take those skills cross-platform
✅ You want file-based routing with automatic deeplinks (Expo Router)
✅ Your app is not blasted with cutting edge native features

One important caveat and requirement for the web though:

✅ Your third party libraries are compatible with React-Native-Web

While the react-native area is pretty big compared to the others, this might be the most limiting factor depending on the complexity of what you're doing for web.

Expo and the React open-source community are putting in tons of work to bring most react-native features to web as well, but it's probably safe to assume that only 60 - 80% will be actually compatible with tools like Expo for Web or Expo's Next.js adapter.

Personal advice when considering switching from web to React-Native: Try building an MVP with your most important react libraries first. If those work, great! If they don't, are there alternatives of equal quality available that do?

Supporting web with React-Native and Expo

The most straight forward way to support Web when choosing React-Native would be to use Expo and its static web output.

However, while they provide an API to get static data at build time, this does not really support frequently updating data like a much more flexible Next.js project would allow for. The API's where you'd get your data from would also need to have their own separate server since there's no API routes when using Expo for Web.

Instead, you might be better off using an Expo + Next.js starter:

When to use an Expo + Next.js starter?

(Since Tamagui uses Solito & both FullProduct.dev and Solito can use Tamagui, I've decided to clump them together for this section) as Expo + Next.js starters:

✅ You want to use Expo + Next.js and don't want to set that up yourself
✅ You want to show an interactive demo of the app on the landing page
✅ Which might mean you need web UI optimized at build time (tamagui)
✅ You're not averse to using a monorepo, or using Next.js API routes

Whichever starter you choose, the fact they all use Next.js also means you get the benefits of easier optimization for web-vitals, which is a must to rank high in search engines.

So where do their differences lie?

When to use which opinionated starter?

So, this is the part where I reveal my bias as the maintainer of FullProduct.dev. Which doesn't mean that I don't also see the usecase for using Tamagui, their newly released premium starter called Takeout or another powerful Solito based starter like T4. Your choice will likely come down to personal preference.

Honestly, all will set you up with a universal app:

📱 Expo with Expo-Router for iOS and Android
🖥 Next.js with the app-dir for Browsers, Servers & API
⛓ Deeplinking between Web & Mobile
🚀 Write-once, render & deploy anywhere

The true difference lies in the way of working.

If you enjoy:

✅ a single cli command to get set-up (create-tamagui-app)
✅ using packages to share code between related software
✅ spending a little more time to fully own your setup
✅ a cool GitHub bot that helps you merge new updates into your project
✅ a more styling & theming focused solution

Then Tamagui / Takeout is likely the solution for you.

But if you're more into:

✅ Tailwind for styling both Web and Mobile
✅ A starter you can personalize so it grows with you
✅ Template Repos and a git-based plugin branch system
✅ The option to still add tRPC and Tamagui later on
✅ A setup designed for copy-paste

as well as

✅ Using zod.dev for Single sources of truth (Types, GraphQL, Stories, DB)
✅ Both GraphQL & REST APIs by writing data resolvers once
✅ Autogenerated docs from zod & the filesystem
✅ A way of working that promotes organizing for copy-paste

and overall:

✅ A pretty scalable setup for your startup without the time investment

Then you might want to check out FullProduct.dev instead.

Thanks for reading!

If you liked this writeup, you may also like my article on how your startup can use cross-platform tech to compete with the Elon Musks of the world:

https://dev.to/codinsonn/how-to-compete-with-elons-twitter-a-dev-perspective-4j64

Here's a quick intro to that post:

'Move fast & build things' with Zod, Expo & Next.js

Musk’s takeover of twitter had a lot of devs looking to swoop in to build the next best thing.

While it isn’t possible to create a new twitter app in just a few weeks ... there ARE ways to gain enough speed to compete with Elon's version of twitter.

I recently delved into this during my first tech talk, titled "Move fast & build things".

I'll re-share the tips & tricks discussed during the talk here:

✅ How to build for iOS, Android and the web, from the start, in a write-once way. (and why you should)
✅ How to scale with ease, Automate your documentation with Storybook, and focus on building your features well and fast instead.

...

💡 Learn more through codinsonn.dev or continue reading on DEV.to

'Move fast & build things' with Zod, Expo & Next.js

Thorr ⚡️ codinsonn.dev — Sun, 13 Nov 2022 21:59:21 +0000

Musk’s takeover of Twitter had a lot of devs looking to swoop in to build the next best thing.

While it isn’t possible to create a new Twitter app in just a few weeks ... there ARE ways to gain enough speed to compete with Elon's version of Twitter.

I recently delved into this during my tech talk "Move fast & build things".

I'll re-share the tips & tricks discussed during the talk here:

✅ How to build for iOS, Android and the web, from the start, in a write-once way. (and why you should)
✅ How to scale with ease, Automate your documentation with Storybook, and focus on building your features well and fast instead.

Why these specific topics? Well, looking at it through the same lens, let's say you have an app in mind…

App idea 💡 New, better Twitter

So, you've chosen to compete with Elon, who is ruining the platform he bought at an alarming rate. But until it IS ruined, you'll need to offer enough similar features, and Twitter has plenty.

Meaning, from the start, you already have to optimize for speed. Playing 'feature catch-up' requires us to literally move fast and build things.

Another thing to consider is Twitter's reach. It is already available for web, iOS, and Android. If you take yourself seriously, you'll need to launch for those platforms as well.

Building in a "Hybrid-first" way becomes a must.

Why?

Well, if you launched something users actually want to use, but it's only available on the web, you'll eventually get comments like these:

While this may just be Elon taunting you as his new competitor, genuinely interested users will be asking exactly the same thing.

This should not come as a surprise, because users increasingly prefer to use the internet in Mobile apps vs Websites.

Elon has a point here. 👇

Building for how users want to consume

Consider this 1-min clip from the App.js conf intro by Expo’s @ccheever

The stats don't lie:

More and more internet use on mobile vs. decline on desktop
90% of that mobile internet use comes from apps
Mobile apps drive up to 3x more conversions than browsers (source)
Yet we keep (mostly) focusing on building websites instead

If you REALLY want to build for how users like to consume, an app in the App + Play Store is what you should aim for.

Consider this section from my current employer's website (Bothrs.com)

Native can get you far, but since you want to move fast, building your features twice, once with Swift for iOS and once for Android, is not very efficient in terms of cost & time.

What you need if you want to build fast, is react-native with Expo.

You can still benefit from the web

The fact that your potential users are more likely to prefer mobile, does not mean you can't still massively benefit from the web.

Organic web search is still a major source of free traffic to your application. When users are searching for answers to their problems, they will more often than not resort to Google first.

All the more reason to show up in their search results.

With new Expo features like @evanbacon's Expo Router, you could easily guide users landing on your site from the web, to your mobile app instead:

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

Ok. We're convinced we have to go cross-platform from the start. But how DO we start building for Web/ iOS/ Android with Expo?

How to start hybrid-first? 🤔

There are a few options:

🤔 Web-first with e.g. create-react-app, add react-native to that setup
🤔 Mobile-first setup, add react-native-web + Next.js for SSR
✅ Start from a cross-platform template

The reason I don't recommend the first two options is because it will be hard to figure out. Trust me, I know. I've been iterating on this "server render react-native" concept since react-native-web and Next.js were a thing.

Let me tell you, it'll take you at least a few days, sometimes weeks before you get to the point you want your initial setup to be.

Also, the clock is ticking, if you're going to beat Twitter, you can't be reinventing the wheel here.

Choose an Expo + Next.js template instead.

Some honorable mentions are:

✅ Solito.dev by @nandorojo (check out his talks on Next.js & App.js conf)
✅ Create-T3-Turbo by @t3dotgg (more opinionated, tRPC for API layer)

These solutions are pretty solid, and you could start your 'Twitter killer' app from either of these.

...but...

How to scale efficiently?

Again: We're competing with Twitter here. You're going to need more engineers. A bunch more.

How can you ease communication between them, and add some efficiency to a team onboarding new people?

Essentially, we want:

🔃 Ways to share some reusable building blocks
📚 Document our ways of working, preferably in 1 space
🤔 To not spend a lot of time writing these docs

Here too, we're trying to avoid reinventing the wheel. You don't want new developers to come in, not understand what's going on, and then decide "Meh. I could probably do this better myself."

No.

If you want to go fast, never reinvent the wheel.

Storybook has a great quote for this:

As good as the other templates are, this is where they tend to fall a bit short. Docs are essential for any project you intend to ship, even if it were just a small team working on it.

Here too, there is an honorable mention: Redwood, for example, does come with Storybook out of the box. Sadly, it is web-first and does not provide a way to do mobile.

If you want to work on your Twitter alternative efficiently with a lot of devs, you're going to need another template.

Introducing... FullProduct.dev

While searching for inspiration on Twitter, you stumble upon this new template to start from, made by yours truly:

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

Curious about how this automatic generation of storybook docs works, you delve into the quickstart to find out.

Automatic docgen with Single sources of truth

What we find is that you can kind of opt into automatic docgen by exporting a getDocumentationProps variable. This should contain a description of your data structure for your props and works kind of similar to how Next.js has you opt into server-side rendering with e.g. getServerSideProps.

This is what the section on automatic docgen in the FullProduct.dev docs looks like:

You think, ok, so all I need to do is give the component the same name as the file, export getDocumentationProps, and some node script/automation will pick it up and spit out some Storybook files? That works for me!

Some more questions do still come up though:

What format should I export my prop structure as?
Will I have to redefine this structure for my types?

We continue down the quickstart and find the answers to our questions:

This uses Zod for single sources of truth? Awesome, that's arguably even more type-safe than typescript itself.

You realize this is a great way to not repeat yourself when it comes to data structure and data validation. Actual "single sources of truth" you can get your type-safety (and editor hints) from, that's pretty neat 🎉

While this makes sense to you now, you're curious what these Storybook files actually render docs-wise. So you open up FullProduct.dev's example Storybook to check that out:

You notice that for every component opting into automatic docgen with getDocumentationProps, there's a markdown powered section in our Storybook with:

✅ Import path for that component + option to copy
✅ Preview of what the component looks like
✅ How to use the component in another React component
✅ Table of all props, with description, defaults & controls

You can even edit these controls in the table and see the preview and code example update live to test out what each prop ends up doing 👀

This is a ton of value you get for describing your prop structure in a specific way.

On top of that, the template supports adding your own Markdown for documenting your ways of working. This should help our newly onboarded devs with knowing what's available and how to build with these blocks themselves, instead of going in blind. ✅

Web, iOS & Android with Expo + Next.js

With docs tackled, you remember being promised an Expo + Next.js setup as well. So you check out the example page the template came with, either online or by cloning a demo repo and running npm run dev:

FullProduct.dev | Universal App Starterkit

We help freelancers, agencies, startups and solopreneurs build their apps for Web and App Stores, in an efficient write-once way.

fullproduct.dev

💡 To open the iOS simulator as well, use npm run dev:mobile instead (with XCode installed)

You compare the web & mobile examples side by side, and notice it comes with some pretty basic template stuff:

Image ➡️ Powered by a src string pointing to a local file in the public folder
Icons for each part of the stack ➡️ Click or tap them for more info
Which file to edit to change this example screen
Confirmation we have some very basic APIs up and running
Internal links to test navigation ➡️ URLs on web, stacks on mobile
External links to e.g. the Aetherspace docs ➡️ New tab or in-app browser

You decide to take the advice of being told where we can throw out all this boilerplate and start writing our own code.

Write-once UI

It's time to write some UI for our Twitter alternative.

In the quickstart, you read up on how to do this in a write-once way:

With primitives like Text, View & Image you can apparently build & style your UI for all the platforms we want to target. This makes sense, you think, since all apps and components eventually are made up of them.

You do wonder why the template includes its own primitives though.

Didn't react-native already have Text, View & Image primitives?

When you ponder a bit longer, you realize that if these primitives are optimized for each of these platforms, then anything built with those primitives should also be optimized for them as well.

To style these primitives for example, you can use tailwind, and some optimizations seem to have been made to make sure things like breakpoints and media queries work for all environments as well. (even though react-native-web does not support this out of the box, hey, Aetherspace has you covered)

Truly native on mobile

Just to be sure, you have a closer look at what your react-native bundle actually looks like.

What you find is very similar to this tweet:

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

While the aetherspace primitives do seem to be translated by react-native to (e.g.) native UIKit layers under the hood, and not some sort of webview rendering a website underneath, doesn't mean they're also optimized for web however, and Elon is just waiting to call us out for it:

Semantic HTML & Web optimisations for SEO

We are competing with Twitter as a text-based platform, so ranking high in search engines will be an important factor in our plan to beat Elon at his own game.

If you were doing e-commerce instead, this would be even more important.

Luckily, FullProduct.dev provides you with aetherspace/html-elements, a small wrapper around @evanbacon's @expo/html-elements:

Take what works and make it better

☝️ That seems to be a common theme in this aetherspace template thing. Like their Image primitive using next/image under the hood, that's bound to improve our SEO ranking:

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

This really solidifies the reason you're choosing a template with Next.js. A close collaboration between their team and the Chrome dev team is likely to help give you a head start when it comes to search engine ranking.

Ok, but: Server rendering is nice, but what about the rest of your back-end?

Write-once APIs

Recognizing you as competition, it doesn't take Elon long before he throws another jab your way:

Fortunately, you remember that the example screen the template came with had status badges for not just one, but TWO apis:

✅ REST, powered by Next.js API routes
✅ GraphQL, powered by Apollo Server

When you click either of these buttons, it opens their endpoints.

For the REST one, you end up at a heath check endpoint at /api/health that tells you the server is alive and kicking:

{
  "alive": true,
  "kicking": true
}

When you check the GraphQL playground at /api/graphql, you see that the exact same health check is available:

Hmm. Are these two APIs using the same resolver underneath? Could you edit the underlying function once to (e.g.) echo back some argument and bring those API changes to both REST and GraphQL in one go...?

Once more, the quickstart provides us with the answer:

Just to recap what you just learned:

1. Define your data structure for input & output with Zod
2. You do this using the same aetherSchema() builder as for docgen
3. You can reuse properties from one schema in another (and more)
4. Business logic is a regular promise, wrapped with createResolver()
5. This bundles your logic with your args & response data structure
6. Export a helper around that bundle to create an API route
7. Export a graphQLResolver pointing to that bundle to enable GraphQL

When you implement this echo functionality and try it out in the GraphQL playground, you notice it now also hints at the docs you defined for your arguments and response:

Another win for single sources of truth.

More value in less time

The final part of the quickstart reflects on everything the 'FullProduct.dev' template helps you with:

Fast forwarding our hypothetical scenario a few months: You've managed to grow your team quite a bit. Some ex-twitter engineers have even joined up. Motivated, highly efficient, and sharing knowledge through docs, your team has quickly been able to recreate a lot of core Twitter features and is ready to launch a first MVP.

Meanwhile at Twitter HQ...

You see, Elon made a grave mistake.

Consider this graphic of what Twitter architecture could look like after 10 years of active development:

Thanks to xkcd and cassiecodes for this graphic

Perhaps firing half your developers and watching a bunch more quit in solidarity wasn't the smartest thing to do Elon.

Eventually something important breaks, and we can all expect this to happen:

When that happens, you, your team, and your alternative will be ready to swoop in and provide a fresh new experience for those fleeing Twitter.

The end.

Things to consider

Obligatory statement to avoid getting banned from Twitter:

Since it's just as important to know when NOT to use a tool:

🤔 If you're in need of cutting-edge native features, like building the next Spotify, this probably won't be the template for you. React-native takes a while to have all the latest native features, Expo takes some time to pick up with the latest react-native version, ... but, this could be fixed with Expo's ability to add custom native code.

🤔 Aetherspace is a starter repo. On top of that it's currently still early days. The core features may be there and the quickstart & docs might cover a lot, but there is more testing to be done on larger-scale projects. Attempting to migrate an existing app to the template is probably a bad idea unless you’re rebranding / rebuilding it from scratch.

🤔 If you're not a fan of Typescript, Monorepos or even React, this will also not be a good fit. ... but if you're instead familiar with another web-based front-end framework, have a look at Capacitor instead for going cross-platform from the start.

When to use FullProduct.dev, from a business perspective:

✅ You want the best of both worlds. Your users may prefer mobile, but even if they don't, you're building for both in a very efficient way.
✅ You want free organic web traffic as a top source of lead generation. Here, Next.js = first class in SEO ranking.
✅ Easily guide users from web to mobile, where more conversions tend to happen.

When to use the template, from a DEV perspective:

✅ You're already familiar with React, and would like to take those skills cross-platform, then this is a great way to do so.
✅ You want to kickstart your next Expo + Next.js project.
✅ You'd like to automate a large part of your documentation or explore what Storybook can do for you.
✅ You love single sources of truth, DRY programming and providing a ton of value in little time.

DEV Community: Thorr ⚡️ codinsonn.dev

Zod and the Joy of Single Sources of Truth

Convert with Type Coercion

Validation Errors

Custom Error Messages

Going beyond TS by narrowing types

Advanced Types: Enums, Tuples and more

There's more:

Bringing it together in Schemas

Why single sources of truth?

Ecosystem Shoutouts

What makes a good Single Source of Truth?

Introspection & Metadata

What's missing in Zod?

Adding Introspection to Zod

Using our custom introspection API

Optionality and Defaults

Single Source of Truth Examples

Designing Database Models with Zod

Generating Docs

Resolvers and Databridges

Zod for simplifying GraphQL

Scaffolding Forms?

Even better DX with Codegen

FullProduct.dev ⚡️ Universal App Starterkit

Like most time-saving templates, it will set you up with:

Why FullProduct.dev ⚡️ ?

Liked this article? 💚

React-Native over Flutter? - How to choose cross-platform tech

Misleading stats?

What the App Stores say

So when does Flutter make sense?

How to choose cross-platform tech?

Knowing this, you should choose Flutter if:

When web, SEO & SSR make sense

When might one use web wrappers for mobile?

When to use tools like React-Native and Expo?

Supporting web with React-Native and Expo

When to use an Expo + Next.js starter?

When to use which opinionated starter?

Thanks for reading!

'Move fast & build things' with Zod, Expo & Next.js

'Move fast & build things' with Zod, Expo & Next.js

App idea 💡 New, better Twitter

Building for how users want to consume

The stats don't lie:

You can still benefit from the web

How to start hybrid-first? 🤔

How to scale efficiently?

Introducing... FullProduct.dev

Automatic docgen with Single sources of truth

Web, iOS & Android with Expo + Next.js

FullProduct.dev | Universal App Starterkit

Write-once UI

Truly native on mobile

Semantic HTML & Web optimisations for SEO

Write-once APIs

More value in less time

Meanwhile at Twitter HQ...

Things to consider

When to use FullProduct.dev, from a business perspective:

When to use the template, from a DEV perspective:

Links & Resources