DEV Community: ajcwebdev

A First Look at SolidStart

ajcwebdev — Wed, 23 Nov 2022 19:22:49 +0000

Outline

Introduction
- A History of SolidJS and How it Compares to React
- SolidJS Benchmark Performance
- SolidStart Motivations
Create Client Rendered Solid Project
- TypeScript and Vite Project Configuration
- HTML Entry, CSS Styling, and Render Function
- Start Development Server
Migrate Project to SolidStart
- SolidStart Scripts and Vite Configuration
- Index Route, Root, and Entry Points
Components and Reactive Primitives
- Create Signal
- Create Effect
- Create Route Data
API Routes
Deployment Adapters
- Deploy to Netlify
- Deploy to Vercel
- Deploy to Cloudflare

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

On November 9, 2022, Ryan Carniato published Introducing SolidStart: The SolidJS Framework to announce the beta launch of SolidStart, the eagerly awaited metaframework for SolidJS. SolidStart provides a first-party project starter and metaframework for SolidJS. It prescribes a recommended way to organize, architect, and deploy SolidJS applications.

Vite is included for the build tool along with extra Solid packages for common functionality and a CLI for generating templated projects. These packages enable features such as routing, MetaTags, different rendering modes, TypeScript support, and deployment adapters. In addition to Node and static hosting, adapters currently exist for the following platforms:

A History of SolidJS and How it Compares to React

Before diving into SolidStart, it's worth taking a moment to outline the history and motivation behind the creation of Solid. Branded as "a reactive JavaScript library for building user interfaces," Ryan open sourced the framework on April 24, 2018. It was designed as a spiritual successor to the reactive programming model exemplified by KnockoutJS.

React wasn’t the first JavaScript “Just a Render Library”. I attribute that honor to a much older library, KnockoutJS. Knockout didn’t have components but identified an application was built from 3 parts, Model, ViewModel, and View, and only cared about how you organized the latter. The ViewModel was a revolutionary concept.

ViewModels are instances much like components. But what set Knockout apart was ViewModels could be anything you wanted; an object, a function, a class. There were no lifecycle functions. You could bring your own models and organize your application as you saw fit. Without best practices it could be a complete mess.

But it was truly “Just a Render Library.” Those boundaries haven’t changed in over a decade... As Controllers transformed to Routers, Models to Stores, and ViewModels/Views got wrapped together as Components, the anatomy of a Component (even in a smaller library like React) is still 3 main parts:

Container

Change (Local State) Manager

Renderer

Ryan Carniato - B.Y.O.F. Writing a JS Framework in 2018 (November 10, 2018)

As the 2010s progressed, Ryan believed the JavaScript world had moved on from using composable reactive primitives in favor of class components and lifecycle methods. Dissatisfied with this direction, Ryan aimed for Solid to be a more modern reactive framework inspired by Knockout but with features informed by newer component frameworks like Angular, React, and Vue.

Shortly after the framework's release, React introduced hooks. Their debut in React Today and Tomorrow and 90% Cleaner React With Hooks, October 26, 2018 became a pivotal moment for Solid. React hooks are functions that can access React state and lifecycle methods from functional components. These functions can be composed into more complex UIs much like Solid.

Within a few years, the majority of React developers would be developing with composable, functional patterns. This ensured that React developers would find Solid easily comprehensible. But despite the surface level similarities between Solid and React's syntax, Solid has a few key advantages over React due to its underlying implementation.

Solid removes the need for some of React's more complex hooks that patch over the leaky abstraction underlying React. useCallback exists to give React developers a mechanism for preventing rerenders. But in Solid, components only mount once and don't rerender so there is no need for an equivalent hook.

SolidJS Benchmark Performance

Solid is also one of the most performant JavaScript libraries. This is evidenced by the results of the JS Framework Benchmark. A large, randomized table of entries is created and modified. Rendering duration is measured along with how long various operations take to complete (lower scores are better).

While admittedly a contrived example, the benchmark allows factoring multiple measurements into a single geometric mean representing comparative performance between frameworks. For a combination of all types of read and write operations, Solid ranks just below vanilla JavaScript:

Framework	Version	Mean
Vanilla JS	N/A	1.00
Solid	1.5.4	1.10
Lit-html	1.1.0	1.19
Vue	3.2.37	1.25
Svelte	3.50.1	1.30
Preact	10.7.3	1.43
Angular	13.0.0	1.58
Marko	4.12.3	1.70
React	18.2.0	1.73

Solid ties vanilla JS and ranks just below Svelte on lighthouse startup metrics:

Framework	Version	Mean
Svelte	3.50.1	1.03
Solid	1.5.4	1.04
Vanilla JS	N/A	1.04
Preact	10.7.3	1.06
Lit-html	1.1.0	1.07
Marko	4.12.3	1.18
Vue	3.2.37	1.27
React	18.2.0	1.69
Angular	13.0.0	1.77

SolidStart Motivations

SolidStart takes influence from other JavaScript metaframeworks including Next.js, Nuxt.js, and SvelteKit by introducing multiple build modes, routing conventions, opinionated project structures, and pre-configured deployment adapters. The framework can produce sites or applications that employ either:

In the future, you'll also be able to choose:

Create Client Rendered Solid Project

mkdir ajcwebdev-solidstart
cd ajcwebdev-solidstart
pnpm init
pnpm add solid-js @solidjs/meta @solidjs/router solid-start
pnpm add -D solid-start-node vite-plugin-solid vite undici typescript

Add vite scripts to package.json and set type to module.

{
  "name": "ajcwebdev-solidstart",
  "version": "1.0.0",
  "description": "An example SolidStart application deployed on Netlify, Vercel, and Cloudflare Pages",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "serve": "vite preview"
  },
  "keywords": [ "SolidJS", "SolidStart", "Netlify", "Vercel", "Cloudflare" ],
  "author": "Anthony Campolo",
  "license": "MIT"
}

Create a .gitignore file.

echo 'node_modules\n.env\n.DS_Store\ndist\n.solid\nnetlify\n.netlify\n.vercel' > .gitignore

There's only a handful of files needed for a working Solid project. These include a configuration file for Vite (vite.config.ts), an entry point for our JavaScript application (src/root.tsx), and an entry point for our HTML page (index.html).

Run the following commands:

mkdir src
echo > tsconfig.json   # TypeScript Configuration
echo > vite.config.ts  # Vite Configuration
echo > index.html      # HTML entry point where JavaScript app loads
echo > src/root.css    # CSS stylesheet
echo > src/root.tsx    # Defines the document the app renders

In addition to the required files we also created optional files for CSS styling and TypeScript configuration. Later in the tutorial when we migrate this project to SolidStart, we'll remove the HTML file and replace it with two files, entry-server.tsx and entry-client.tsx.

TypeScript and Vite Project Configuration

Copy/paste this impenetrable hunk of gibberish into your tsconfig.json and say a prayer to Microsoft.

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "strict": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "jsxImportSource": "solid-js",
    "jsx": "preserve",
    "types": ["vite/client"],
    "baseUrl": "./",
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

The vite.config.ts file is where we'll add the Solid Plugin to define our Vite Configuration. Import solidPlugin from vite-plugin-solid and add it to the plugins array inside Vite's defineConfig helper.

// vite.config.ts

import solidPlugin from "vite-plugin-solid"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [solidPlugin()]
})

HTML Entry, CSS Styling, and Render Function

The root Solid component will be imported as an ESM module from /src/root.tsx and set to the src attribute.

<!-- index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="An example SolidJS single-page application." />
    <title>A First Look at SolidStart</title>
  </head>

  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <script src="/src/root.tsx" type="module"></script>
  </body>
</html>

Include the following CSS styles in src/root.css.

/* src/root.css */

body {
  background-color: #282c34;
  color: white;
  font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
  margin: 0;
  text-align: center;
}

header {
  font-size: calc(10px + 2vmin);
  margin: 1rem;
}

a {
  color: #b318f0;
}

To mount Solid and automatically create a reactive root, import render from solid-js/web and pass in two arguments, a top-level component function and an element to mount on:

The first argument returns the root component and must be passed a function.
The mounting container is passed for the second argument and wired up to the root div.

// src/root.tsx

/* @refresh reload */
import { render } from "solid-js/web"
import "./root.css"

function App() {
  return (
    <>
      <header>
        <h1>A First Look at SolidStart</h1>
        <a href="https://github.com/solidjs/solid">Learn Solid</a>
      </header>
      <footer>
        <span>
          Visit <a href="https://ajcwebdev.com">ajcwebdev.com</a> for more tutorials
        </span>
      </footer>
    </>
  )
}

render(
  () => <App />, document.getElementById('root') as HTMLElement
)

Start Development Server

pnpm dev # or npm run dev | yarn dev

Open localhost:5173 to view the running application in your browser. The page will reload if you make edits.

At this point, we could build and deploy a dist folder to any static host provider. Run pnpm build and pnpm serve to test serving your bundle on localhost:4173. Instead of deploying this project, we'll continue to the next section and begin modifying our project to make it work with SolidStart.

Migrate Project to SolidStart

First, delete your existing HTML file and create a routes directory inside src.

rm -rf index.html
mkdir src/routes
echo > src/entry-server.tsx # Server entry point
echo > src/entry-client.tsx # Browser entry point
echo > src/routes/index.tsx # Home route

SolidStart Scripts and Vite Configuration

Replace the Vite scripts with the following SolidStart scripts.

{
  "scripts": {
    "dev": "solid-start dev",
    "build": "solid-start build",
    "start": "solid-start start"
  },
}

Remove solidPlugin from vite-plugin-solid and replace it with solid from solid-start/vite.

// vite.config.ts

import solid from "solid-start/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [solid()]
})

Index Route, Root, and Entry Points

Copy the App component from src/root.tsx and include it in src/routes/index.tsx with export default.

// src/routes/index.tsx

export default function App() {
  return (
    <>
      <header>
        <h1>A First Look at SolidStart</h1>
        <a href="https://github.com/solidjs/solid">Learn Solid</a>
      </header>
      <footer>
        <span>
          Visit <a href="https://ajcwebdev.com">ajcwebdev.com</a> for more tutorials
        </span>
      </footer>
    </>
  )
}

root.tsx is the point where your code runs on both the server and client. It exports a Root component that is shared on the server and browser as an isomorphic entry point to your application. Since SolidStart is designed for file-system routing, routes are defined via a folder structure under the /routes folder. You can pass them into the <Routes> component with the <FileRoutes> component.

This collects routes from the file-system in the /routes folder to be inserted into a parent <Routes> component. Since <FileRoutes> returns a route configuration, it must be placed directly between <Routes>, typically in the root.tsx file. <Routes> is a special Switch component that renders the correct <Route> child based on the users' location, and switches between them as the user navigates.

// src/root.tsx

// @refresh reload
import { Suspense } from "solid-js"
import { Body, ErrorBoundary, FileRoutes, Head, Html, Meta, Routes, Scripts, Title } from "solid-start"
import "./root.css"

export default function Root() {
  return (
    <Html lang="en">
      <Head>
        <Title>A First Look at SolidStart</Title>
        <Meta charset="utf-8" />
        <Meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta name="description" content="An example SolidStart application deployed on Netlify, Vercel, and Cloudflare Pages." />
      </Head>
      <Body>
        <ErrorBoundary>
          <Suspense fallback={<div>Loading...</div>}>
            <Routes>
              <FileRoutes />
            </Routes>
          </Suspense>
        </ErrorBoundary>
        <Scripts />
      </Body>
    </Html>
  )
}

entry-client.tsx starts the application in the browser by passing <StartClient> to a mount function. mount is an alias over Solid's hydrate and render methods. It ensures that the client always starts up properly whether you are using SolidStart for client-only rendering or server-side rendering.

// src/entry-client.tsx

import { mount, StartClient } from "solid-start/entry-client"

mount(() => <StartClient />, document)

entry-server.tsx starts the application on the server by passing <StartServer> to a render function called renderAsync. createHandler enables a mechanism for introducing middleware into server rendering. <StartServer> wraps the application root and includes Context providers for Routing and MetaData. It takes the Event object originating from the underlying runtime and includes information such as the request, responseHeaders and status codes.

// src/entry-server.tsx

import { StartServer, createHandler, renderAsync } from "solid-start/entry-server"

export default createHandler(
  renderAsync((event) => <StartServer event={event} />)
)

While this example uses renderAsync, there are three different render functions provided by SolidStart. Each wraps Solid's rendering method and returns a unique output:

renderSync calls renderToString to synchronously respond immediately and render the application to a string.
renderAsync calls renderToStringAsync to asynchronously respond when the page has fully been loaded and render the application to a promise.
renderStream calls renderToStream to asynchronously respond as soon as it can and render the application to a ReadableStream.

Check that everything still displays as expected.

pnpm dev

Open localhost:3000.

Components and Reactive Primitives

Since this is a tutorial about a frontend framework it will be considered illegitimate until we build a counter. Create a components directory and then a file called Counter.tsx inside of it.

mkdir src/components
echo > src/components/Counter.tsx

There are two foundational building blocks at the core of Solid's fine grained reactivity that will enable us to craft this magnificent counter into existence:

Components contain stateless DOM elements within functions that accept props and return JSX elements.
Reactive Primitives including Signals, Effects, and Memos track and broadcast the changing values that represent the state of the components over time.

In this component we'll create a signal to track the changing value of the counter and an effect to modify the value with button clicks.

Create Signal

Signals contain values that change over time. They are tracked by the framework and update automatically by broadcasting to the rest of the interface. Use createSignal to initialize a value of 0 and set it to count. Increment the counter once every second by passing a setCount(count() + 1) function to a setInterval() method that executes every 1000 milliseconds.

// src/components/Counter.tsx

import { createSignal } from "solid-js"

export default function Counter() {
  const [count, setCount] = createSignal(0)

  setInterval(() => setCount(count() + 1), 1000)

  return (
    <>The count is now: {count()}</>
  )
}

Inside src/routes/index.tsx, import Counter from ../components/Counter. Return a <Counter /> component in the return function of the App component.

// src/routes/index.tsx

import Counter from "../components/Counter"

export default function App() {
  return (
    <>
      <header>
        <h1>A First Look at SolidStart</h1>
        <a href="https://github.com/solidjs/solid">Learn Solid</a>
      </header>
      <main>
        <Counter />
      </main>
      <footer>
        <span>
          Visit <a href="https://ajcwebdev.com">ajcwebdev.com</a> for more tutorials
        </span>
      </footer>
    </>
  )
}

Create Effect

An Effect is an example of an observer that runs a side effect depending on a signal. createEffect creates a new computation (for example to modify the DOM manually) and runs the given function in a tracking scope.

// src/components/Counter.tsx

import { createSignal, createEffect } from "solid-js"

export default function Counter() {
  const [count, setCount] = createSignal(0)

  createEffect(() => count())

  return (
    <>
      <button onClick={() => setCount(count() + 1)}>
        Click Me
      </button>
      <div>The count is now: {count()}</div>
    </>
  )
}

This automatically tracks the dependencies and reruns the function whenever the dependencies update.

Create Route Data

Create a new file called students.tsx inside the src/routes directory. This will contain a third party API call to return a list of Harry Potter characters.

echo > src/routes/students.tsx

createRouteData is a wrapper over createResource for handling async data fetching and refetching. With SolidStart's file system routing, components defined under /routes can utilize a routeData function which executes when navigation to that component begins. This hook returns the JSON parsed data from the loader function. We'll use the Fetch API to query Harry Potter information on Deno Deploy.

// src/routes/students.tsx

import { useRouteData, createRouteData } from "solid-start"

type Student = { name: string; }

export function routeData() {
  return createRouteData(async () => {
    const response = await fetch("https://hogwarts.deno.dev/students")
    return (await response.json()) as Student[]
  })
}

export default function Page() { }

This routeData function can be thought of like a "loader" function (what a brilliant idea, amazing no one thought of it before) which includes a useRouteData hook to access the returned data.

// src/routes/students.tsx

import { useRouteData, createRouteData } from "solid-start"

type Student = { name: string; }

export function routeData() {
  return createRouteData(async () => {
    const response = await fetch("https://hogwarts.deno.dev/students")
    return (await response.json()) as Student[]
  })
}

export default function Page() {
  const students = useRouteData<typeof routeData>()

  return (
    <>
      <header>
        <h1>Students</h1>
      </header>
      <main>
        <code>{JSON.stringify(students(), null, 2)}</code>
      </main>
    </>
  )
}

useRouteData can use whatever data is returned from the routeData loader function.

The <For> component loops over an array of objects. The <For> component has only one prop, each, which is passed an array to loop over with a callback similar to JavaScript's map callback.

// src/routes/students.tsx

import { useRouteData, createRouteData } from "solid-start"
import { For } from "solid-js"

type Student = { name: string; }

export function routeData() {
  return createRouteData(async () => {
    const response = await fetch("https://hogwarts.deno.dev/students")
    return (await response.json()) as Student[]
  })
}

export default function Page() {
  const students = useRouteData<typeof routeData>()

  return (
    <>
      <header>
        <h1>Students</h1>
      </header>
      <main>
        <For each={students()}>
          {student => <li>{student.name}</li>}
        </For>
      </main>
    </>
  )
}

API Routes

API routes are similar to other routes except instead of exporting a default Solid component with a routeData function, they export functions that are named after the HTTP methods they handle such as GET or POST.

mkdir src/routes/api
echo > src/routes/api/index.ts

json is a helper function to send JSON HTTP responses. Return a JSON object with the key set to hello and the value set to world.

// src/routes/api/index.ts

import { json } from "solid-start"

export function GET() {
  return json(
    { hello: "world" }
  )
}

Open 127.0.0.1:3000/api or make a request with cURL.

curl http://127.0.0.1:3000/api

{"hello":"world"}

Deployment Adapters

Here is the directory and file structure for the final project before including any files related to deployment:

.
├── src
│   ├── components
│   │   └── Counter.tsx
│   ├── routes
│   │   ├── api
│   │   │   └── index.ts
│   │   ├── index.tsx
│   │   └── students.tsx
│   ├── entry-client.tsx
│   ├── entry-server.tsx
│   ├── root.css
│   └── root.tsx
├── package.json
├── tsconfig.json
└── vite.config.ts

Push your project to a GitHub repository.

git init
git add .
git commit -m "mr solid"
gh repo create ajcwebdev-solidstart \
  --description="An example SolidJS application deployed on Netlify, Vercel, and Cloudflare Pages." \
  --remote=upstream \
  --source=. \
  --public \
  --push

If you only want to use a single deployment platform, select one of the next three options and push the changes to the main branch. I will deploy the project to all three by creating a different branch for each and specifying the correct branch on the deployment platform.

Deploy to Netlify

Import the netlify adapter from solid-start-netlify.

// vite.config.ts

// @ts-ignore
import netlify from "solid-start-netlify"
import solid from "solid-start/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [solid({
    adapter: netlify({ edge: true })
  })]
})

Install solid-start-netlify and the Netlify CLI.

pnpm add -D solid-start-netlify netlify-cli @types/node

Create a netlify.toml file for the build instructions.

echo > netlify.toml

Set the command to pnpm build and the publish directory to netlify.

# netlify.toml

[build]
  command = "pnpm build"
  publish = "netlify"

Connect the repository to your Netlify account through the Netlify dashboard or use the following commands with the Netlify CLI.

pnpm ntl login
pnpm ntl init

The build commands will be automatically entered from the netlify.toml file.

pnpm ntl deploy --prod --build

Open ajcwebdev-solidstart.netlify.app to see a running example.

Deploy to Vercel

Install solid-start-vercel and the Vercel CLI.

pnpm add -D solid-start-vercel vercel

Import the vercel adapter from solid-start-vercel.

// vite.config.ts

// @ts-ignore
import vercel from "solid-start-vercel"
import solid from "solid-start/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [solid({
    adapter: vercel({ edge: true })
  })]
})

Deploy the project with the Vercel CLI.

pnpm vercel --yes --prod

Open ajcwebdev-solidstart.vercel.app.

Deploy to Cloudflare

SolidStart includes two adapters for Cloudflare, one for Cloudflare Workers and another for Cloudflare Pages. It's important to note that the Cloudflare Pages adapter is also using Workers through Pages Functions. Install solid-start-cloudflare-pages and the wrangler CLI.

pnpm add -D solid-start-cloudflare-pages wrangler

Import the cloudflare adapter from solid-start-cloudflare-pages.

// vite.config.ts

// @ts-ignore
import cloudflare from "solid-start-cloudflare-pages"
import solid from "solid-start/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [solid({
    adapter: cloudflare({})
  })],
})

Build the project's assets and run a local Worker emulation on localhost:8788 with wrangler pages dev.

pnpm wrangler login
pnpm build
pnpm wrangler pages dev ./dist/public

Create a project with wrangler pages project create and deploy the project with wrangler pages publish.

pnpm wrangler pages project create ajcwebdev-solidstart \
  --production-branch production
pnpm wrangler pages publish dist/public \
  --project-name=ajcwebdev-solidstart \
  --branch=production

Open ajcwebdev-solidstart.pages.dev.

A First Look at create-t3-app

ajcwebdev — Sat, 13 Aug 2022 08:16:00 +0000

Outline

Introduction
- Why the t3 Stack Was Created
- History of the t3 Stack and Create Nex App
Create t3 App
- Project Structure
- Tailwind Styles
Provision PostgreSQL Database
- Add Posts Model to Prisma Schema
- Initialize Railway Database and Run Migration
- Seed a Blog Post
Query Posts with tRPC
- Create Post Router
- Create App Router
- Query Posts with useQuery
Add Cells for Declarative Data Fetching
- Create Default Query Cell
- Create Post Page
- Create Posts Cell
Deployment
- Deploy to Vercel
- Deploy to Fly
Resources, Articles, and Videos

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

create-t3-app is a fullstack React framework and CLI that has emerged as an evolution of the T3 stack recommended on Theo Browne's website init.tips. It's described by its creators as "kind of a template," which is meant to stress that it is "NOT a template".

Why the t3 Stack Was Created

ct3a's goal is to provide the quickest way to start a new fullstack, typesafe web application. To achieve this goal, the stack is architected around three foundational constituents that together can be bundled together and used to develop monolithic applications:

Typed React frontend (TypeScript and Next.js)
Typed database client (Prisma)
Typed remote procedure calls (tRPC)

Depending on your background and perspective that may sound like a ground breaking innovation, a completely obvious repackaging of techniques used over two decades ago, or an absolute heresy because you've been taught that developing monoliths is a sin.

Source: Sabin Adams - End-To-End Type Safety

As someone who has resisted TypeScript until now, this is terrifying to me. But I'm going to make an exception and embrace TypeScript for the first time in my life if this stack can actually provide a smooth and streamlined TypeScript experience.

But for those already in love with TypeScript and fullstack React frameworks, you are probably feeling a strange sense of deja-vu right now. This is an almost identical stack to Blitz.js and shares many of the same architectural principles. The notable difference is that CTA includes tRPC (which itself has frequently been compared to Blitz.js).

History of the t3 Stack and Create Nex App

The first iteration of the init.tips site suggested only one command was needed to initialize a mostly optimal boilerplate for the majority of web applications in 2021. This suggestion (in its infinite wisdom) was: Create a Next.js app, but with TypeScript.

As people began to consider this advice, many developers inevitably asked:

"Mmmm, but what about all that other stuff not included in this stack that I need to make an even borderline functional application?"

This lead to other recommendations for add-ons to the stack. These add-ons targeted specific use cases such as:

Prisma for managing database migrations and SQL queries through an ORM
Next-auth for client side authentication
Tailwind for CSS and UI styling
tRPC for end-to-end typesafe APIs

If these were being frequently recommended, it stood to reason that it would make sense to create a new, more full featured command. This would generate not only a typed Next.js project, but one with an ORM, authentication, styling, and API protocol.

These would be automatically included while also giving you the ability to opt out if you still want the bare-bones version. I'm happy that this is taking off and that some consider it a novel idea.

I've spent the last two years relentlessly promoting frameworks assembling different versions of these kinds of stacks. RedwoodJS, Blitz.js, and Bison all have extremely similar but also slightly different stacks. To understand how these relate to each other, I would break it down like so:

This is not meant to be an exhaustive list and I've purposefully left off things like tests, mocks, Storybook, deployment, and other non-architectural pieces.

As the project has evolved from init.tips to create-t3-app, it has taken on a life of its own. Theo has stated numerous times that he did not actually initiate the creation of create-t3-app, he simply talked about the idea numerous times in public.

In fact, he never would have had the time to build or manage such a project. On top of full time content creation, he's the CEO of a startup building ping.gg, a collaborative streaming tool. His influence over the project primarily stemmed from his various public discussions of the stack.

These discussions inspired a group of people who were members of his recently formed Discord server. This online space was created to bring together fans of his Twitch and YouTube channels. A group independently began building out a full fledged project. This activity was centered around the work of Shoubhit Dash.

Known as nexxel or nexxeln online, Shoubhit took the initiative to formalize the stack by developing an interactive CLI tool that would be able to scaffold out a project using arbitrary combinations of the various technologies used in the stack. nexxel, a 17 year old self-taught developer, is the true rosetta stone to this project.

Nexxel was blogging about tRPC in May right before launching the framework. Build end to end typesafe APIs with tRPC signaled the birth of the framework on May 21, 2022 along with an initial commit on May 20, 2022. Originally called Create Nex App, the README described the project like so:

Scaffold a starting project using the t3 stack using this interactive CLI.

The early prototypes of the project included Next.js, Tailwind, and TypeScript along with tRPC. Throughout June, the project began attracting around a dozen contributors. Julius Marminge (juliusmarminge) was one of the earliest contributors and remains active today.

Roughly a month later on June 26, 2022, nexxel published T3 stack and my most popular open source project ever. This blog post was published after working with the other contributors to fully integrate Prisma and Next Auth, marking the completion of the stack's initial integration phase.

Throughout the month of June, the GitHub repo gained nearly 2,000 GitHub stars. Despite having only been created at the end of May, the project had reached nearly unprecedented levels of momentum. On July 17, 2022, nexxel migrated his personal blog to create-t3-app and by the middle of August the project had over 5,000 stars.

Create t3 App

To get started with ct3a, you can run any of the following three commands and answer the command prompt questions:

npx create-t3-app@latest

yarn create t3-app

pnpm dlx create-t3-app@latest

The following CLI options are currently available:

Option	Description
`--noGit`	Explicitly tell the CLI to not initialize a new git repo in the project
`-y`, `--default`	Bypass CLI and use all default options to bootstrap new t3-app
`[dir]`	Include a directory argument with a name for the project
`--noInstall`	Generate project without installing dependencies

We'll give our project a name and select all available options with the exception of NextAuth.

pnpm dlx create-t3-app@latest ajcwebdev-t3

I will select the following options:

? Will you be using JavaScript or TypeScript?  TypeScript
? Which packages would you like to enable?     prisma, tailwind, trpc
? Initialize a new git repository?             Yes
? Would you like us to run 'pnpm install'?     Yes

Including the -y option will select the default configuration which bundles all four packages into the project. The interactive CLI prompt will also ask whether you want to use JavaScript or TypeScript. If you try to select JavaScript though, you will discover that the option is but a mere illusion. In fact, you must use TypeScript and also there is no God.

Using: pnpm

✔ ajcwebdev-t3 scaffolded successfully!

✔ Successfully setup boilerplate for prisma
✔ Successfully setup boilerplate for tailwind
✔ Successfully setup boilerplate for trpc
✔ Successfully setup boilerplate for envVariables
✔ Successfully installed dependencies!
✔ Successfully initialized git

Enter your project directory and start the development server.

cd ajcwebdev-t3
pnpm dev

Open localhost:3000 to see the generated project.

Project Structure

If we ignore the configuration files in the root of our project then our folder and file structure includes the following:

.
├── prisma
│   └── schema.prisma
├── public
│   └── favicon.ico
└── src
    ├── env
    │   ├── client.mjs
    │   ├── schema.mjs
    │   └── server.mjs
    ├── pages
    │   ├── _app.tsx
    │   ├── api
    │   │   ├── examples.ts
    │   │   └── trpc
    │   │       └── [trpc].ts
    │   └── index.tsx
    ├── server
    │   ├── db
    │   │   └── client.ts
    │   └── trpc
    │       ├── context.ts
    │       ├── router
    │       │   ├── _app.ts
    │       │   └── example.ts
    │       └── trpc.ts
    ├── styles
    │   └── globals.css
    └── utils
        └── trpc.ts

We'll break down each of these different directories and files as we progress through the tutorial. But as a quick overview, we'll be primarily working with:

Pages and API Routes
- src/pages/index.tsx
- src/pages/api/examples.ts
- src/pages/api/trpc/[trpc].ts
Server and Database
- src/server/db/client.ts
- src/server/trpc/context.ts
- src/server/trpc/router/_app.ts
- src/server/trpc/router/example.ts
- src/server/trpc/trpc.ts
Styling
- src/styles/globals.css
Utilities
- src/utils/trpc.ts

Tailwind Styles

Open src/pages/index.tsx and make some changes to customize the home page. Feel free to follow along or make your own alterations, there are many different ways this project could be organized. First, I will create a file called file called home-styles.ts to hold all styling that will be used on the home page of the website.

echo > src/styles/home-styles.ts

I will export a variable defining each Tailwind style that can be reused throughout the project.

// src/styles/home-styles.ts

export const appContainer = "container mx-auto flex flex-col items-center justify-center min-h-screen p-4"
export const title = "text-5xl md:text-[5rem] leading-normal font-extrabold text-gray-700"
export const purple = "text-purple-300"
export const body = "text-2xl text-gray-700"
export const grid = "grid gap-3 pt-3 mt-3 text-center md:grid-cols-2 lg:w-2/3"
export const queryResponse = "pt-6 text-2xl text-blue-500 flex justify-center items-center w-full"

appContainer styles the main content
title styles the page's h1 header
purple styles T3 with its signature purple color
body styles the p tag introducing the list of technologies included in the stack
grid styles the div wrapping the TechnologyCard components
queryResponse styles the div wrapping the tRPC hello query

Add these style variables to the Home component.

// src/pages/index.tsx

import Head from "next/head"
import { trpc } from "../utils/trpc"
import {
  appContainer, title, purple, body, grid, queryResponse
} from "../styles/home-styles"

export default function Home() {
  const hello = trpc.useQuery([
    "example.hello",
    { text: "from tRPC" }
  ])

  return (
    <>
      <Head>
        <title>A First Look at create-t3-app</title>
        <meta name="description" content="Example t3 project from A First Look at create-t3-app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={appContainer}>
        <h1 className={title}>
          Create <span className={purple}>T3</span> App
        </h1>

        <p className={body}>This stack uses:</p>

        <div className={grid}>...</div>
        <div className={queryResponse}>...</div>
      </main>
    </>
  )
}

echo > src/styles/card-styles.ts

Add style variables to the TechnologyCard component:

cardSection styles the card's container on the section element
cardTitle styles the technology's title on each card
cardDescription styles the description of each technology
link styles the link on each card

// src/styles/card-styles.ts

export const cardSection = "flex flex-col justify-center p-6 duration-500 border-2 border-gray-500 rounded shadow-xl motion-safe:hover:scale-105"
export const cardTitle = "text-lg text-gray-700"
export const cardDescription = "text-sm text-gray-600"
export const link = "mt-3 text-sm underline text-violet-500 decoration-dotted underline-offset-2"

// src/pages/index.tsx

import Head from "next/head"
import { trpc } from "../utils/trpc"
import { appContainer, title, purple, body, grid, queryResponse } from "../styles/home-styles"
import { cardSection, cardTitle, cardDescription, link } from "../styles/card-styles"

type TechnologyCardProps = {...}

const TechnologyCard = ({ name, description, documentation }: TechnologyCardProps) => {
  return (
    <section className={cardSection}>
      <h2 className={cardTitle}>
        {name}
      </h2>

      <p className={cardDescription}>
        {description}
      </p>

      <a className={link} href={documentation} target="_blank" rel="noreferrer">
        Documentation
      </a>
    </section>
  )
}

Now I will modify the four cards to include links to my blog and social media profiles. With that change in mind, I will use url instead of documentation for a more appropriate prop name. I will also change the links to include the entire card within the anchor tags so clicking anywhere on the card will open the hyperlink.

// src/pages/index.tsx

import Head from "next/head"
import { trpc } from "../utils/trpc"
import {
  appContainer, title, purple, body, grid, queryResponse, cardSection, cardTitle, cardDescription, link
} from "../styles/home-styles"

type TechnologyCardProps = {
  name: string
  url: string
}

const TechnologyCard = ({ name, url }: TechnologyCardProps) => {
  return (
    <a href={`https://${url}`} target="_blank" rel="noreferrer">
      <section className={cardSection}>
        <h2 className={cardTitle}>
          {name}
        </h2>

        <span className={link}>
          {url}
        </span>
      </section>
    </a>
  )
}

export default function Home() {
  const hello = trpc.useQuery([
    "example.hello",
    { text: "from tRPC" }
  ])

  return (
    <>
      <Head>
        <title>A First Look at create-t3-app</title>
        <meta name="description" content="Example t3 project from A First Look at create-t3-app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={appContainer}>
        <h1 className={title}>
          Hello from <span className={purple}>ajc</span>webdev
        </h1>

        <div className={grid}>
          <TechnologyCard name="Blog" url="ajcwebdev.com/" />
          <TechnologyCard name="Twitter" url="twitter.com/ajcwebdev/" />
          <TechnologyCard name="GitHub" url="github.com/ajcwebdev/" />
          <TechnologyCard name="Polywork" url="poly.work/ajcwebdev/" />
        </div>

        <div className={queryResponse}>
          {
            hello.data
              ? <p>{hello.data.greeting}</p>
              : <p>Loading..</p>
          }
        </div>
      </main>
    </>
  )
}

Return to localhost:3000 to see the changes.

Lastly, I will abstract out the TechnologyCard component into its own file and rename it to Card.

mkdir src/components
echo > src/components/Card.tsx

Rename TechnologyCardProps to CardProps and create a Card component.

// src/components/Card.tsx

import { cardSection, cardTitle, link } from "../styles/home-styles"

type CardProps = {
  name: string
  url: string
}

export default function Card({
  name, url
}: CardProps) {
  return (
    <a href={`https://${url}`} target="_blank" rel="noreferrer">
      <section className={cardSection}>
        <h2 className={cardTitle}>
          {name}
        </h2>

        <span className={link}>
          {url}
        </span>
      </section>
    </a>
  )
}

Import Card into src/pages/index.tsx and remove CardProps.

// src/pages/index.tsx

import Head from "next/head"
import Card from "../components/Card"
import { appContainer, title, purple, grid } from "../styles/home-styles"

export default function Home() {
  return (
    <>
      <Head>
        <title>A First Look at create-t3-app</title>
        <meta
          name="description"
          content="Example t3 project from A First Look at create-t3-app"
        />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={appContainer}>
        <h1 className={title}>
          Hello from <span className={purple}>ajc</span>webdev
        </h1>

        <div className={grid}>
          <Card name="Blog" url="ajcwebdev.com/" />
          <Card name="Twitter" url="twitter.com/ajcwebdev/" />
          <Card name="GitHub" url="github.com/ajcwebdev/" />
          <Card name="Polywork" url="poly.work/ajcwebdev/" />
        </div>
      </main>
    </>
  )
}

Provision PostgreSQL Database

Since this a fullstack framework, it already includes a tool called Prisma for working with our database. Our models will be defined in the prisma/schema.prisma file along with our specific database provider.

Add Posts Model to Prisma Schema

The initial generated project has the database datasource set to SQLite. Since we want to use a real database, open schema.prisma and update the datasource to the PostgreSQL provider.

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

In addition to the current models in the schema, add a Post model with an id, title, description, body, and createdAt timestamp.

// prisma/schema.prisma

model Post {
  id                String    @id
  title             String
  description       String
  body              String
  createdAt         DateTime  @default(now())
}

Also, uncomment all appearances of @db.Text on the Account model.

// prisma/schema.prisma

model Account {
  id                String    @id @default(cuid())
  userId            String
  type              String
  provider          String
  providerAccountId String
  refresh_token     String?   @db.Text
  access_token      String?   @db.Text
  expires_at        Int?
  token_type        String?
  scope             String?
  id_token          String?   @db.Text
  session_state     String?
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@unique([provider, providerAccountId])
}

Initialize Railway Database and Run Migration

We'll use Railway to provision a PostgreSQL database. First, you need to create a Railway account and install the Railway CLI. If you are unable to login through the browser, run railway login --browserless instead.

railway login

Run the following command, select "Empty Project," and give your project a name.

railway init

To provision the database, add a plugin to your Railway project and select PostgreSQL.

railway add

Set the DATABASE_URL environment variable for your database and create a .env file to hold it.

echo DATABASE_URL=`railway variables get DATABASE_URL` > .env

Run a migration with prisma migrate dev to generate the folders and files necessary to create a new migration. We'll name our migration init with the --name argument.

pnpm prisma migrate dev --name init

After the migration is complete, generate the Prisma client with prisma generate.

pnpm prisma generate

Seed a Blog Post

Right now we'll avoid implementing an endpoint through our app with write, update, or delete functionality since we'll not be including authentication in this section. However, there are at least five different ways you can write data to your database. If you want to skip this section, the tl;dr is send raw SQL queries through the Railway Query dashboard.

The Railway dashboard provides three separate methods for accessing your database (not including using the connection string itself as an environment variable in the project as we'll do later):

Execute raw SQL queries under the Query tab
Connect to database with the psql command under the Connect tab
Enter data with Railway's UI under the Data tab

For Prisma, you can either:

Login to the Prisma Data Platform at cloud.prisma.io
Run Prisma Studio on localhost 5555 with pnpm prisma studio

Note: I'm including Prisma Studio here for completion's sake, but I advise against using it. It's a seemingly sleek and polished product with a very strange input bug that causes it to throw out a value if you don't click away from the input before adding the record to the table. This means you can create a record and have a crucial field get totally wiped and replaced with a blank value.

Yes, this is should just be for a test database, and yes it's just dummy data. But still, to me, especially for a database tool, this seems fundamentally broken and I honestly can't recommend using this tool in good conscious. I first experienced this bug around the end of 2021 and you can view a recording of the bug in action on an episode of Teach Jenn Tech recorded in November 2022.

GUIs are more intuitive for developers without much SQL experience. But unfortunately, they can also be buggy or cumbersome. You especially don't want to be entering every row by hand when you need to input large amounts of data at once. SQL commands provide a more consistent and scalable technique for seeding a database or entering ongoing new data.

The first option on the list (execute raw SQL queries under the Query tab on Railway's dashboard) gives us the best of both worlds. It does not require entering data into any GUI but it also does not require installing a Postgres client like psql to your local machine and connecting to a database instance over the network. We could create a blog post with the following command:

INSERT INTO "Post" (id, title, description, body) VALUES (
  '1',
  'A Blog Post Title',
  'This is the description of a blog post',
  'The body of the blog post is here. It is a very good blog post.'
);

This SQL command can be entered directly into the text area under the Query tab.

Click "Run query" and then add two more blog posts:

INSERT INTO "Post" (id, title, description, body) VALUES (
  '2',
  'Second Blog Post',
  'This is the description of ANOTHER blog post',
  'Even better than the last!'
);
INSERT INTO "Post" (id, title, description, body) VALUES (
  '3',
  'The Final Blog Post',
  'This is the description for my final blog post',
  'My blogging career is over. This is the end, thank you.'
);

Query Posts with tRPC

tRPC is a library that is designed for writing typesafe APIs. Instead of importing server code, the client only imports a single TypeScript type. tRPC transforms this type into a fully typesafe client that can be called from the frontend.

Create Post Router

Create a file to initialize a router instance called postRouter. This will query for all of our posts.

echo > src/server/router/post.ts

Add a query endpoint to the router with the .query() method. It with accept two arguments: name for the name of the endpoint and params for query parameters.

// src/server/router/post.ts

import { createRouter } from "./context"

export const postRouter = createRouter()
  .query('all', {
    async resolve() {
      // Add Prisma query
    },
  })

params.resolve implements the endpoint which will be a function with a single req argument that runs the Prisma Client findMany query which returns a list of records, in this case all posts based on the post model.

// src/server/router/post.ts

import { prisma } from "../db/client"
import { createRouter } from "./context"

export const postRouter = createRouter()
  .query('all', {
    async resolve() {
      return prisma.post.findMany()
    },
  })

params.input provides input validation and will be discussed in the Create Default Query Cell section.

Create App Router

In src/server/router/index.ts, there is a base appRouter for our server entry point. This can be gradually extended with more types and resolved into a single object.

// src/server/router/index.ts

import superjson from "superjson"
import { createRouter } from "./context"
import { exampleRouter } from "./example"
import { protectedExampleRouter } from "./protected-example-router"

export const appRouter = createRouter()
  .transformer(superjson)
  .merge("example.", exampleRouter)
  .merge("question.", protectedExampleRouter)

export type AppRouter = typeof appRouter

Import postRouter and use the .merge() method to combine the following three routes into a single appRouter instance:

exampleRouter
postRouter
protectedExampleRouter

// src/server/router/index.ts

import superjson from "superjson"
import { createRouter } from "./context"
import { exampleRouter } from "./example"
import { postRouter } from "./post"
import { protectedExampleRouter } from "./protected-example-router"

export const appRouter = createRouter()
  .transformer(superjson)
  .merge("example.", exampleRouter)
  .merge("post.", postRouter)
  .merge("question.", protectedExampleRouter)

export type AppRouter = typeof appRouter

Queries related to blog posts will be prefixed with post (post.all, post.byId). The hello query example will be prefixed with example as seen earlier with example.hello.

Query Posts with useQuery

Open src/pages/index.tsx to query all posts and display them on the home page. Create a Posts component and initialize a variable called postsQuery above the return statement. Set the postsQuery variable to the output of post.all with the useQuery() hook.

// src/pages/index.tsx

import Head from "next/head"
import { trpc } from "../utils/trpc"
import {
  appContainer, title, purple, body, grid, queryResponse, cardSection, cardTitle, cardDescription, link
} from "../styles/home-styles"
import Card from "../components/Card"

const Posts = () => {
  const postsQuery = trpc.useQuery([
    'post.all'
  ])

  return (...)
}

export default function Home() {...}

As mentioned in the previous section, the appRouter object can be inferred on the client. Stringify the JSON output from postsQuery.data and display the data below the title of the page.

// src/pages/index.tsx

const Posts = () => {
  const postsQuery = trpc.useQuery([
    'post.all'
  ])

  const { data } = postsQuery

  return (
    <div className={queryResponse}>
      {data
        ? <p>{JSON.stringify(data)}</p>
        : <p>Loading..</p>
      }
    </div>
  )
}

Return Posts in the Home component.

// src/pages/index.tsx

export default function Home() {
  return (
    <>
      <Head>
        <title>A First Look at create-t3-app</title>
        <meta name="description" content="Example t3 project from A First Look at create-t3-app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={appContainer}>
        <h1 className={title}>
          Hello from <span className={purple}>ajc</span>webdev
        </h1>

        <div className={grid}>
          <Card name="Blog" url="ajcwebdev.com/" />
          <Card name="Twitter" url="twitter.com/ajcwebdev/" />
          <Card name="GitHub" url="github.com/ajcwebdev/" />
          <Card name="Polywork" url="poly.work/ajcwebdev/" />
        </div>

        <Posts />
      </main>
    </>
  )
}

We have some conditional logic to ensure that a loading message is displayed if the data has not yet returned from the server. But what if there are no blog posts in the database or the server returns an error? This is a case that would be perfectly suited for a Cell.

Add Cells for Declarative Data Fetching

One of my favorite patterns from Redwood that I have been hoping to see in other frameworks is the concept of a Cell. Cells provide a built-in convention for declarative data fetching that isn't exactly a state machine but shares common benefits and characteristics.

Unlike general purpose finite-state machines, Cells are specifically focused on common data fetching outcomes. They give developers the ability to avoid writing any conditional logic since a cell will manage what happens during the following four potential states of your data fetching:

Success - Display the response data
Failure - Handle the error message and provide instructions to the user
Empty - Show a message or graphic communicating an empty list
Loading - Show a message or graphic communicating the data is still loading

Thankfully, my hopes were fulfilled when lead tRPC maintainer, Alex Johansson opened a PR with a tRPC Cell example that he acknowledged was influenced by RedwoodJS.

Create Default Query Cell

createQueryCell is used to bootstrap DefaultQueryCell which can be used anywhere in your application.

echo > src/utils/DefaultQueryCell.tsx

Ideally this will one day be internal to either tRPC or create-t3-app and you'll be able to just write cells without thinking about it. But for now, we need to create this ourselves.

// src/utils/DefaultQueryCell.tsx

import { TRPCClientErrorLike } from "@trpc/client"
import NextError from "next/error"
import type { AppRouter } from "../server/router/index"
import {
  QueryObserverIdleResult,
  QueryObserverLoadingErrorResult,
  QueryObserverLoadingResult,
  QueryObserverRefetchErrorResult,
  QueryObserverSuccessResult,
  UseQueryResult,
} from "react-query"

type JSXElementOrNull = JSX.Element | null

type ErrorResult<TData, TError> =
  | QueryObserverLoadingErrorResult<TData, TError>
  | QueryObserverRefetchErrorResult<TData, TError>

interface CreateQueryCellOptions<TError> {
  error: (query: ErrorResult<unknown, TError>) => JSXElementOrNull
  loading: (query: QueryObserverLoadingResult<unknown, TError>) => JSXElementOrNull
  idle: (query: QueryObserverIdleResult<unknown, TError>) => JSXElementOrNull
}

interface QueryCellOptions<TData, TError> {
  query: UseQueryResult<TData, TError>
  error?: (query: ErrorResult<TData, TError>) => JSXElementOrNull
  loading?: (query: QueryObserverLoadingResult<TData, TError>) => JSXElementOrNull
  idle?: (query: QueryObserverIdleResult<TData, TError>) => JSXElementOrNull
}

interface QueryCellOptionsWithEmpty<TData, TError>
  extends QueryCellOptions<TData, TError> {
  success: (query: QueryObserverSuccessResult<NonNullable<TData>, TError>) => JSXElementOrNull
  empty: (query: QueryObserverSuccessResult<TData, TError>) => JSXElementOrNull
}
interface QueryCellOptionsNoEmpty<TData, TError>
  extends QueryCellOptions<TData, TError> {
  success: (query: QueryObserverSuccessResult<TData, TError>) => JSXElementOrNull
}

function createQueryCell<TError>(
  queryCellOpts: CreateQueryCellOptions<TError>,
) {
  function QueryCell<TData>(opts: QueryCellOptionsWithEmpty<TData, TError>): JSXElementOrNull
  function QueryCell<TData>(opts: QueryCellOptionsNoEmpty<TData, TError>): JSXElementOrNull
  function QueryCell<TData>(opts:
    | QueryCellOptionsNoEmpty<TData, TError>
    | QueryCellOptionsWithEmpty<TData, TError>,
  ) {
    const { query } = opts

    if (query.status === 'success') {
      if ('empty' in opts &&
        (query.data == null ||
          (Array.isArray(query.data) && query.data.length === 0))
      ) {
        return opts.empty(query)
      }
      return opts.success(query as QueryObserverSuccessResult<NonNullable<TData>, TError>)
    }

    if (query.status === 'error') {
      return opts.error?.(query) ?? queryCellOpts.error(query)
    }
    if (query.status === 'loading') {
      return opts.loading?.(query) ?? queryCellOpts.loading(query)
    }
    if (query.status === 'idle') {
      return opts.idle?.(query) ?? queryCellOpts.idle(query)
    }
    return null
  }
  return QueryCell
}

type TError = TRPCClientErrorLike<AppRouter>

export const DefaultQueryCell = createQueryCell<TError>({
  error: (result) => (
    <NextError
      title={result.error.message}
      statusCode={result.error.data?.httpStatus ?? 500}
    />
  ),
  idle: () => <div>Loading...</div>,
  loading: () => <div>Loading...</div>,
})

We want to be able to query an individual blog post based on its id. Create a post page with a dynamic route based on the id.

mkdir src/pages/post
echo > src/pages/post/\[id\].tsx

Since we'll be sending data to the database, we need to validate the input. zod is a TypeScript schema validator with static type inference. We'll also import TRPCError for error handling.

// src/server/router/post.ts

import { prisma } from "../db/client"
import { TRPCError } from "@trpc/server"
import { z } from "zod"
import { createRouter } from "./context"

export const postRouter = createRouter()
  .query('all', {
    async resolve() {
      return prisma.post.findMany()
    }
  })

Add byId query to Post router in src/server/router/post.ts and destructure the id from the input.

// src/server/router/post.ts

import { prisma } from "../db/client"
import { TRPCError } from "@trpc/server"
import { z } from "zod"
import { createRouter } from "./context"

export const postRouter = createRouter()
  .query('all', {
    async resolve() {
      return prisma.post.findMany()
    }
  })

  .query('byId', {
    input: z.object({ id: z.string() }),
    async resolve({ input }) {
      const { id } = input
    },
  })

findUnique query lets you retrieve a single database record based on the id provided by passing it to Prisma's where option.

// src/server/router/post.ts

import { prisma } from "../db/client"
import { TRPCError } from "@trpc/server"
import { z } from "zod"
import { createRouter } from "./context"

export const postRouter = createRouter()
  .query('all', {
    async resolve() {
      return prisma.post.findMany()
    }
  })

  .query('byId', {
    input: z.object({ id: z.string() }),
    async resolve({ input }) {
      const { id } = input
      const post = await prisma.post.findUnique({
        where: { id }
      })
    },
  })

Last but not least, throw an error with TRPCError if a post is not returned.

// src/server/router/post.ts

import { prisma } from "../db/client"
import { TRPCError } from "@trpc/server"
import { z } from "zod"
import { createRouter } from "./context"

export const postRouter = createRouter()
  .query('all', {
    async resolve() {
      return prisma.post.findMany()
    }
  })

  .query('byId', {
    input: z.object({ id: z.string() }),
    async resolve({ input }) {
      const { id } = input
      const post = await prisma.post.findUnique({
        where: { id }
      })
      if (!post) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: `No post with id '${id}'`
        })
      }
      return post
    }
  })

Create Post Page

Import DefaultQueryCell in src/pages/post/[id].tsx and create a component called PostPage.

// src/pages/post/[id].tsx

import { useRouter } from "next/router"
import Head from "next/head"
import { DefaultQueryCell } from "../../utils/DefaultQueryCell"
import { trpc } from "../../utils/trpc"

export default function PostPage() {
  return (...)
}

Return DefaultQueryCell and pass postQuery to query and data to success.

// src/pages/post/[id].tsx

import { useRouter } from "next/router"
import Head from "next/head"
import { DefaultQueryCell } from "../../utils/DefaultQueryCell"
import { trpc } from "../../utils/trpc"

export default function PostPage() {
  const id = useRouter().query.id as string
  const postQuery = trpc.useQuery([
    'post.byId',
    { id }
  ])

  return (
    <DefaultQueryCell
      query={postQuery}
      success={({ data }) => (
        <>
          <Head>
            <title>{data.title}</title>
            <meta name="description" content={data.description} />
          </Head>

          <main>
            <h1>{data.title}</h1>
            <p>{data.body}</p>
            <em>Created {data.createdAt.toLocaleDateString()}</em>
          </main>
        </>
      )}
    />
  )
}

Lastly, add blogContainer, blogTitle, and blogBody for styling the posts.

// src/pages/post/[id].tsx

import { useRouter } from "next/router"
import Head from "next/head"
import { DefaultQueryCell } from "../../utils/DefaultQueryCell"
import { trpc } from "../../utils/trpc"
import { blogContainer, blogTitle, blogBody } from "../../styles/blog-styles"

export default function PostPage() {
  const id = useRouter().query.id as string
  const postQuery = trpc.useQuery([
    'post.byId',
    { id }
  ])

  return (
    <DefaultQueryCell
      query={postQuery}
      success={({ data }) => (
        <>
          <Head>
            <title>{data.title}</title>
            <meta name="description" content={data.description} />
          </Head>

          <main className={blogContainer}>
            <h1 className={blogTitle}>
              {data.title}
            </h1>
            <p className={blogBody}>
              {data.body}
            </p>

            <em>Created {data.createdAt.toLocaleDateString()}</em>
          </main>
        </>
      )}
    />
  )
}

Open localhost:3000/post/1 to see your first blog post.

Create Posts Cell

echo > src/components/PostsCell.tsx
echo > src/styles/blog-styles.ts

// src/styles/blog-styles.ts

export const blogContainer = "container mx-auto min-h-screen p-4"
export const blogTitle = "text-5xl leading-normal font-extrabold text-gray-700"
export const blogBody = "mb-2 text-lg text-gray-700"
export const blogHeader = "text-5xl leading-normal font-extrabold text-gray-700"

Create a PostsCell function and import the following above it:

Link for linking to each blog post's page
blogHeader and link for styling the list output from the Cell
DefaultQueryCell for creating the cell
trpc for executing the query

// src/components/PostsCell.tsx

import Link from "next/link"
import { blogHeader, link } from "../styles/blog-styles"
import { DefaultQueryCell } from "../utils/DefaultQueryCell"
import { trpc } from "../utils/trpc"

export default function PostsCell() {
  return (...)
}

Create a type called BlogPostProps with an id and title of type string. Delete the Posts component in src/pages/index.tsx and move the useQuery hook into the PostsCell component.

// src/components/PostsCell.tsx

import Link from "next/link"
import { blogHeader, link } from "../styles/blog-styles"
import { DefaultQueryCell } from "../utils/DefaultQueryCell"
import { trpc } from "../utils/trpc"

type BlogPostProps = {
  id: string
  title: string
}

export default function PostsCell() {
  const postsQuery = trpc.useQuery([
    'post.all'
  ])

  return (...)
}

Return DefaultQueryCell with the query set to postsQuery. success will map over the data object and display a link for each blog post.

// src/components/PostsCell.tsx

import Link from "next/link"
import { blogHeader, link } from "../styles/blog-styles"
import { DefaultQueryCell } from "../utils/DefaultQueryCell"
import { trpc } from "../utils/trpc"

type BlogPostProps = {
  id: string
  title: string
}

export default function PostsCell() {
  const postsQuery = trpc.useQuery([
    'post.all'
  ])

  return (
    <>
      <h2 className={blogHeader}>Posts</h2>

      {postsQuery.status === 'loading'}

      <DefaultQueryCell
        query={postsQuery}
        success={({ data }: any) => (
          data.map(({id, title}: BlogPostProps) => (
            <Link key={id} href={`/post/${id}`}>
              <p className={link}>
                {title}
              </p>
            </Link>
          ))
        )}
        empty={() => <p>WE NEED POSTS!!!</p>}
      />
    </>
  )
}

Import PostsCell in src/pages/index.tsx and return the component in the Home function.

// src/pages/index.tsx

import Head from "next/head"
import { appContainer, title, purple, grid } from "../styles/home-styles"
import Card from "../components/Card"
import PostsCell from "../components/PostsCell"

export default function Home() {
  return (
    <>
      <Head>
        <title>A First Look at create-t3-app</title>
        <meta name="description" content="Example t3 project from A First Look at create-t3-app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={appContainer}>
        <h1 className={title}>
          Hello from <span className={purple}>ajc</span>webdev
        </h1>

        <div className={grid}>
          <Card name="Blog" url="ajcwebdev.com/" />
          <Card name="Twitter" url="twitter.com/ajcwebdev/" />
          <Card name="GitHub" url="github.com/ajcwebdev/" />
          <Card name="Polywork" url="poly.work/ajcwebdev/" />
        </div>

        <PostsCell />
      </main>
    </>
  )
}

Deployment

Commit your current changes and create a new repository on GitHub with the GitHub CLI.

git add .
git commit -m "ct3a"
gh repo create ajcwebdev-t3 --public --push \
  --source=. \
  --description="An example T3 application with Next.js, Prisma, tRPC, and Tailwind deployed on Vercel and Fly." \
  --remote=upstream

Deploy to Vercel

Install the vercel CLI on your machine or add it to your project with pnpm.

pnpm add -D vercel

Use the following command to pass your database environment variable and deploy to Vercel. Use --confirm to give the default answer for each question.

pnpm vercel --env DATABASE_URL=YOUR_URL_HERE

After the first deployment this command will deploy to a preview branch. You will need to include --prod to push changes directly to the live site for future deployments.

Open ajcwebdev-t3.vercel.app to see your blog.

API endpoints are exposed on api/trpc/, so ajcwebdev-t3.vercel.app/api/trpc/post.all will display all blog posts.

Or you can hit the endpoint with curl:

curl "https://ajcwebdev-t3.vercel.app/api/trpc/post.all" | npx json

{
  "id": null,
  "result": {
    "type": "data",
    "data": {
      "json": [
        {
          "id": "1",
          "title": "A Blog Post Title",
          "description": "This is the description of a blog post",
          "body": "The body of the blog post is here. It is a very good blog post.",
          "createdAt": "2022-08-13T08:30:59.344Z"
        },
        {
          "id": "2",
          "title": "Second Blog Post",
          "description": "This is the description of ANOTHER blog post",
          "body": "Even better than the last!",
          "createdAt": "2022-08-13T08:36:59.790Z"
        },
        {
          "id": "3",
          "title": "The Final Blog Post",
          "description": "This is the description for my final blog post",
          "body": "My blogging career is over. This is the end, thank you.",
          "createdAt": "2022-08-13T08:40:32.133Z"
        }
      ],
      "meta": {
        "values": {...}
      }
    }
  }
}

For single blog posts try any of the following:

And copy them to the end of:

https://ajcwebdev-t3.vercel.app/api/trpc/post.byId?batch=1&input=

Check PageSpeed Insights for Desktop here.

If what I know about these metrics is correct, then I believe 100 is considered a preferable score when compared to other scores which are not 100.

Check PageSpeed Insights for Mobile here.

100 again! Equally as preferable!!

Deploy to Fly

Since create-t3-app is mostly Next.js and Prisma at the end of the day, it can be deployed very easily on platforms like Vercel. But, in return for that ease of use, you will be taking a performance hit whenever your database is queried.

When Prisma is running in a Lambda function it has a noticeable cold start. Future guides in the ct3a documentation will demonstrate how to use platforms like Fly, Railway, and Render to deploy your project to a long running server. Install the flyctl CLI and run the following command to initialize your project.

fly launch --remote-only \
  --name ajcwebdev-t3 \
  --region ord \
  --env DATABASE_URL=YOUR_URL_HERE

flyctl platform regions to see available regions.

Resources, Articles, and Videos

create.t3.gg
- Repo
- Documentation
init.tips
- Repo
- Documentation

Date	Title
2022-08-10	Build a full stack app with create-t3-app
2022-07-10	ct3a End to End Tutorial Proposal
2022-06-26	T3 stack and my most popular open source project ever
2022-05-21	Build end to end typesafe APIs with tRPC

Date	Title
2022-07-17	Build a Live Chat Application with the T3 Stack
2022-07-12	The T3 Stack - How We Built It
2022-07-10	An Overview of the create T3 App
2022-07-03	The BEST Stack For Your Next Project
2022-06-28	Build a Blog With the T3 Stack

A First Look at Ethers and Hardhat

ajcwebdev — Fri, 04 Mar 2022 06:01:05 +0000

Outline

Introduction
Create Project
- Install Dependencies
- Initialize Hardhat Environment
- Sample Deployment Script
- Hardhat Configuration
- Greeter Solidity Contract
Deploy to Testnet
- Compile Application Binary Interface
- Start Test Node
- Run Deployment Script
Connect to MetaMask
- Import Account into MetaMask
Create React App
- Start Development Server
- Connect React App to MetaMask
Deploy to Ropsten Testnet
- Connect MetaMask to Ropsten
- Create an Alchemy Account
- Create an Alchemy Application
- Get Alchemy Key
- Add Alchemy Endpoint to Hardhat Configuration
- Deploy Contract to Ropsten

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

ethers.js is a library that aims to be a complete and compact tool for interacting with the Ethereum Blockchain and its ecosystem. This example uses Hardhat, an Ethereum development environment, to compile a smart contract and deploy it to Ropsten, an Ethereum test network that allows for blockchain development testing.

The contract is written in Solidity, an object-oriented, high-level language for implementing smart contracts. After deploying the contract, we will generate a boilerplate React application with Vite and connect the application to our smart contract running on Ropsten. Alchemy provides a managed node that enables connecting to various tools in the blockchain ecosystem.

Create Project

This article is heavily based on Nader Dabit's definitive article, The Complete Guide to Full Stack Ethereum Development. I've made a few alternations including using Vite instead of Create React App and the inclusion of dotenv for environment variables but all credit due to Sensei Dabit.

pnpm create vite ajcwebdev-ethers --template react
cd ajcwebdev-ethers

Remove "type": "module" from package.json.

Install Dependencies

In addition to Ethers and Hardhat we will also install Waffle and Chai for testing our contracts.

pnpm add dotenv ethers hardhat chai ethereum-waffle \
   @nomiclabs/hardhat-ethers @nomiclabs/hardhat-waffle

Create a .env file to store environment variables later in the tutorial.

touch .env

The file will include the following three variables:

ALCHEMY_URL=
ALCHEMY_KEY=
VITE_GREETER_ADDRESS=

Initialize Hardhat Environment

Developing smart contracts requires the ability to deploy your contracts, run tests, and debug Solidity code. We will also need a way to compile Solidity code into code that can be run in a client-side application. Hardhat compiles your contracts and runs them on a development network. This lets you develop without having to deal with live environments.

We'll create the following files/directories:

hardhat.config.js - Entire Hardhat setup including config, plugins, and custom tasks.
scripts - Contains a script named deploy.js that deploys your smart contract when executed
contracts - Contains a file called Greeter.sol with an example Solidity smart contract

mkdir scripts contracts
echo > scripts/deploy.js
echo > contracts/Greeter.sol
echo > hardhat.config.js

Sample Deployment Script

In deploy.js we use getContractFactory to create a ContractFactory, an abstraction used to deploy new smart contracts. Greeter is a factory for instances of our greeting contract. Calling deploy() on a ContractFactory will start the deployment, and return a Promise that resolves to a Contract. This is the object that has a method for each of your smart contract functions. Modify the text to send your own message.

// scripts/deploy.js

const hre = require("hardhat")

async function main() {
  const Greeter = await hre.ethers.getContractFactory("Greeter")
  const greeter = await Greeter.deploy("Hello from ajcwebdev!")
  await greeter.deployed()
  console.log("Greeter deployed to:", greeter.address)
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })

I'll also add a few more console logs to the main function to log additional pieces of information including the signer, hash, and blockHash.

// scripts/deploy.js

const hre = require("hardhat")

async function main() {
  const Greeter = await hre.ethers.getContractFactory("Greeter")
  const greeter = await Greeter.deploy("Hello from ajcwebdev!")
  await greeter.deployed()

  console.log("Greeter deployed to " + greeter.address + " address")
  console.log("Greeter deployed by " + JSON.stringify(greeter.signer) + " signer")
  console.log("Deploy transaction hash: " + greeter.deployTransaction.hash)
  console.log("Deploy transaction block hash: " + greeter.deployTransaction.blockHash)
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })

Hardhat Configuration

When Hardhat is run, it searches for the closest hardhat.config.js file starting from the current working directory. This file normally lives in the root of your project. The entirety of your Hardhat setup, including your config, plugins and custom tasks, is contained in this file.

We need to make a couple changes to our hardhat.config.js file. Update the chain ID to 1337 and change the location for the artifacts of the compiled contracts to the src directory of the React app.

// hardhat.config.js

require("@nomiclabs/hardhat-waffle")

task("accounts", "Prints the list of accounts", async (taskArgs, hre) => {
  const accounts = await hre.ethers.getSigners()
  for (const account of accounts) {
    console.log(account.address)
  }
})

/**
 * @type import('hardhat/config').HardhatUserConfig
 */
module.exports = {
  solidity: "0.8.7",
  paths: {
    artifacts: './src/artifacts',
  },
  networks: {
    hardhat: {
      chainId: 1337
    }
  }
}

Greeter Solidity Contract

Solidity files start with a pragma that is used by the Solidity compiler to validate its version. contract specifies the main building block for the smart contract, which is named Greeter.

// contracts/Greeter.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.7;

import "hardhat/console.sol";

contract Greeter { }

The constructor is executed only once when the contract is created. The Greeter constructor will set a greeting variable and expose a function (greet) that can be called to return the greeting. It also exposes a function called setGreeting that allows a user to update the greeting.

// contracts/Greeter.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.7;

import "hardhat/console.sol";

contract Greeter {
  string private greeting;

  constructor(string memory _greeting) {
    console.log("Deploying a Greeter with greeting: ", _greeting);
    greeting = _greeting;
  }

  function greet() public view returns (string memory) {
    return greeting;
  }

  function setGreeting(string memory _greeting) public {
    console.log("Changing greeting from '%s' to '%s'", greeting, _greeting);
    greeting = _greeting;
  }
}

These methods will be available for a user to interact with when deployed to the Ethereum blockchain. These methods represent the two ways of interacting with a smart contract:

greet reads from the blockchain and does not require money for gas.
setGreeting writes to the blockchain and requires payment for the transaction if you want to deploy to mainnet and not a testnet.

Deploy to Testnet

To deploy to the local network, you first need to compile your contract and then start a local test node. Our React app will interact with the smart contract using a combination of the Ethers library, the contract address, and the ABI that will be created from the contract by hardhat.

Compile Application Binary Interface

ABI stands for application binary interface. It is the interface between your client-side application and the Ethereum blockchain where the smart contract you are going to be interacting with is deployed.

pnpm hardhat compile

ABIs are typically compiled from Solidity smart contracts by a development framework like Hardhat. You can also often find the ABIs for a smart contract on Etherscan.

Start Test Node

pnpm hardhat node

This will return a list of addresses and private keys.

Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

Accounts
========
Account #0: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266 (10000 ETH)
Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Account #1: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8 (10000 ETH)
Private Key: 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d

...

We will need to pick an account and corresponding private key. I will use Account #11:

Account #11: 0x71be63f3384f5fb98995898a86b02fb2426c5788 (10000 ETH)
Private Key: 0x701b615bbdfb9de65240bc28bd21bbc0d996645a3dd57e7b12bc2bdf6f192c82

Leave this terminal running and open another for the next command.

Run Deployment Script

Run the deploy script and give a flag to the CLI to let it know that we would like to deploy to our local network:

pnpm hardhat run scripts/deploy.js \
  --network localhost

This will result in the following output in your terminal:

Greeter deployed to 0x5FbDB2315678afecb367f032d93F642f64180aa3 address
Greeter deployed by "<SignerWithAddress 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266>" signer
Deploy transaction hash: 0x74b10cb0666183a9f2d5d20dff6cbf12f2d026d39ce7c48db0f9bb02f52f2ee1
Deploy transaction block hash: 0xfb0865cdff882c11ee07521ed2732b4c961c915d88d407953336484e6ffd2395

The address returned on the first line (0x5FbDB2315678afecb367f032d93F642f64180aa3) is what we will use in our client application to talk to the smart contract. Save this address somewhere that you can access later as we will need to use it when connecting to the contract from the client application.

Connect to MetaMask

To send transactions to the smart contract, we will need to connect our MetaMask wallet using one of the accounts created when we ran pnpm hardhat node. In the terminal running our local node, you will see the following output verifying that the Greeter contract was successfully deployed.

web3_clientVersion
eth_chainId
eth_accounts
eth_blockNumber
eth_chainId (2)
eth_estimateGas
eth_getBlockByNumber
eth_feeHistory
eth_sendTransaction
  Contract deployment: Greeter
  Contract address:    0x5fbdb2315678afecb367f032d93f642f64180aa3
  Transaction:         0x74b10cb0666183a9f2d5d20dff6cbf12f2d026d39ce7c48db0f9bb02f52f2ee1
  From:                0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
  Value:               0 ETH
  Gas used:            505488 of 505488
  Block #1:            0xfb0865cdff882c11ee07521ed2732b4c961c915d88d407953336484e6ffd2395

  console.log:
    Deploying a Greeter with greeting: Hello from ajcwebdev!

eth_chainId
eth_getTransactionByHash
eth_chainId
eth_getTransactionReceipt

In the list of contracts that the CLI logs out, you should see both an Account number as well as a Private Key for the account you originally chose at the beginning of the tutorial. We can import this account into MetaMask in order to start using some of its fake Eth. To do so, first open MetaMask and check the available networks.

If you only see the Ethereum Mainnet, go to Settings > Advanced and make sure "Show test networks" is set to ON.

Update the network to Localhost 8545.

Import Account into MetaMask

Once you are connected to Localhost 8545, click the icon at the top right to see your accounts. Select "Import Account."

Go back to the list of accounts printed by pnpm hardhat node and copy the account's private keys. I'll be using Account #11.

After importing the account you will see ether in the account.

If you are using MetaMask for other purposes, it will be important to distinguish this account from an account that is actually holding funds. Go to "Account details."

Click the pencil icon next to the account name to give it a more descriptive name.

Create React App

Set greeterAddress to the contract address logged out to the CLI when it was deployed. I have created an environment variable named VITE_GREETER_ADDRESS in a .env file. Any environment variables that need to be exposed on the client must be prefixed with VITE_.

// src/App.js

import { useState } from 'react'
import { ethers } from 'ethers'
import Greeter from './artifacts/contracts/Greeter.sol/Greeter.json'

const greeterAddress = import.meta.env.VITE_GREETER_ADDRESS

function App() { }

export default App

We'll import the useState hook and set the state to greeting with setGreetingValue. fetchGreeting will call the smart contract and read the current greeting value.

// src/App.js

import { useState } from 'react'
import { ethers } from 'ethers'
import Greeter from './artifacts/contracts/Greeter.sol/Greeter.json'

const greeterAddress = import.meta.env.VITE_GREETER_ADDRESS

function App() {
  const [greeting, setGreetingValue] = useState()

  async function requestAccount() {
    await window.ethereum.request({ method: 'eth_requestAccounts' })
  }

  async function fetchGreeting() {
    if (typeof window.ethereum !== 'undefined') {
      const provider = new ethers.providers.Web3Provider(window.ethereum)
      const contract = new ethers.Contract(greeterAddress, Greeter.abi, provider)
      try {
        const data = await contract.greet()
        setGreetingValue(data)
        console.log('Greeting: ', data)
        console.log('Contract Address: ', contract.address)
        console.log('Contract Network: ', contract.provider._network.name)
      } catch (err) {
        console.log("Error: ", err)
      }
    }    
  }

  return (
    <div>
      <header>
        <h1>Ethers.js, Hardhat, Solidity</h1>
        <h2>and React, Alchemy, and MetaMask</h2>
      </header>

      <main>
        <h3>Greeting</h3>

        <button onClick={fetchGreeting}>
          Fetch Greeting
        </button>

        <div>{greeting}</div>
      </main>
    </div>
  )
}

export default App

I'll include Water.css in index.html for some nice looking CSS defaults.

<!-- index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css">
    <title>A First look at Ethers and Hardhat</title>
  </head>

  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Start Development Server

Start the development server with pnpm dev.

pnpm dev

Open localhost:3000.

Click the "Fetch Greeting" button to display the greeting from the deployed contract.

setGreeting calls the smart contract and sends an update.

// src/App.js

import { useState } from 'react'
import { ethers } from 'ethers'
import Greeter from './artifacts/contracts/Greeter.sol/Greeter.json'

const greeterAddress = import.meta.env.VITE_GREETER_ADDRESS

function App() {
  const [greeting, setGreetingValue] = useState()

  async function requestAccount() {
    await window.ethereum.request({ method: 'eth_requestAccounts' })
  }

  async function fetchGreeting() {
    if (typeof window.ethereum !== 'undefined') {
      const provider = new ethers.providers.Web3Provider(window.ethereum)
      const contract = new ethers.Contract(greeterAddress, Greeter.abi, provider)
      try {
        const data = await contract.greet()
        setGreetingValue(data)
        console.log('Greeting: ', data)
        console.log('Contract Address: ', contract.address)
        console.log('Contract Network: ', contract.provider._network.name)
      } catch (err) {
        console.log("Error: ", err)
      }
    }    
  }

  async function setGreeting() {
    if (!greeting) return
    if (typeof window.ethereum !== 'undefined') {
      await requestAccount()
      const provider = new ethers.providers.Web3Provider(window.ethereum)
      const signer = provider.getSigner()
      const contract = new ethers.Contract(greeterAddress, Greeter.abi, signer)
      const transaction = await contract.setGreeting(greeting)
      await transaction.wait()
      fetchGreeting()
    }
  }

  return (
    <div>
      <header>
        <h1>Ethers.js, Hardhat, Solidity</h1>
        <h2>and React, Alchemy, and MetaMask</h2>
      </header>

      <main>
        <h3>Greeting</h3>

        <button onClick={fetchGreeting}>
          Fetch Greeting
        </button>
        <div>{greeting}</div>

        <input
          onChange={e => setGreetingValue(e.target.value)}
          placeholder="Set greeting" 
        />
        <button onClick={setGreeting}>
          Set Greeting
        </button>
      </main>
    </div>
  )
}

export default App

Connect React App to MetaMask

Select account to connect with MetaMask.

Connect to the account.

Enter input and click Set Greeting. You will be asked to pay a gas fee.

The greeting value will be set to the new inputted greeting.

Deploy to Ropsten Testnet

Ethereum provides test networks like Ropsten, Rinkeby, or Kovan that we can use to deploy a publicly accessible version of our contract without having to deploy it to the mainnet.

Connect MetaMask to Ropsten

Update your MetaMask wallet to connect to the Ropsten network.

We can get access to Ropsten and other test networks by using a service like Infura, Alchemy, or QuickNode.

Create an Alchemy Account

Alchemy Supernode is a blockchain API that can connect to various tools in the blockchain ecosystem such as Ethereum, Polygon, Arbitrum, Optimism, and Flow. It provides common node functionality including JSON-RPC support with built in reliability, data correctness and scalability. After creating an account, you will see your dashboard.

Create an Alchemy Application

Click Create App and give your app a name and description. Select development for the environment, Ethereum for the chain, and Ropsten for the network.

After creating the app you will see it appear in your dashboard.

Get Alchemy Key

Click the name of the app to see more details.

Click View Key to see your endpoints.

The https endpoint will look something like this:

https://eth-ropsten.alchemyapi.io/v2/PROJECT_ID

Click Edit App and add the account address from App.jsx to the allowed accounts.

Add Alchemy Endpoint to Hardhat Configuration

Open hardhat.config.js and add networks property.

// hardhat.config.js

require("@nomiclabs/hardhat-waffle")
require('dotenv').config()

const { ALCHEMY_URL, ALCHEMY_KEY } = process.env

task("accounts", "Prints the list of accounts", async (taskArgs, hre) => {
  const accounts = await hre.ethers.getSigners()

  for (const account of accounts) {
    console.log(account.address)
  }
})

/**
 * @type import('hardhat/config').HardhatUserConfig
 */
module.exports = {
  solidity: "0.8.7",
  defaultNetwork: "hardhat",
  paths: {
    artifacts: './src/artifacts',
  },
  networks: {
    hardhat: {},
    ropsten: {
      url: `${ALCHEMY_URL}`,
      accounts: [`0x` + `${ALCHEMY_KEY}`]
    }
  }
}

Deploy Contract to Ropsten

Send yourself test Ether by visiting a test faucet like faucet.ropsten.be or faucet.dimensions.network. Run the following script to deploy.

pnpm hardhat run scripts/deploy.js \
  --network ropsten

Greeter deployed to 0x42839A6cD421B0C29AcD3FB900feAa6a76f34684 address
Greeter deployed by "<SignerWithAddress 0x71bE63f3384f5fb98995898A86B02Fb2426c5788>" signer
Deploy transaction hash: 0x9f5875c939d804501767690d843aefb05d91f4b1f5d34d477dbe6d7327c83ca4
Deploy transaction block hash: null

Once your contract is deployed you can view the live contract on Etherscan Ropsten Testnet Explorer.

Querying MongoDB with Prisma and Railway

ajcwebdev — Tue, 01 Feb 2022 07:44:36 +0000

Outline

Introduction
Create Prisma Project
- Initialize Prisma Schema
- Prisma Schema
Provision a MongoDB Database with Railway
- Railway Dashboard
- Railway CLI
Connect Railway Database to Prisma Project
- Set Environment Variable
- Seed Database
- Generate Prisma Client
Create a Script to Query the Database
- Run the Script

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

In this guide we will deploy a MongoDB database with Railway, add seed data to the database, connect to the database through a connection string, and create a Node script to query that seed data with Prisma Client.

Create Prisma Project

Create a blank new project and initialize a package.json.



mkdir railway-prisma-mongodb
cd railway-prisma-mongodb
yarn init -y

Install the prisma dependencies.



yarn add @prisma/client
yarn add -D prisma

Set type to module in package.json.



{
  "name": "railway-prisma-mongodb",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "@prisma/client": "^3.10.0"
  },
  "devDependencies": {
    "prisma": "^3.10.0"
  },
  "type": "module"
}

Initialize Prisma Schema

prisma init scaffolds a basic Prisma project.



yarn prisma init

The only other necessary file is index.js. This is used for running test commands against our database with the Prisma Client.



touch index.js

Our project now has the following structure:



/
├── prisma
│   └── schema.prisma
├── .env
├── .gitignore
├── index.js
└── package.json

Prisma Schema

Define a Post model by adding the following to the schema.prisma file.



datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["mongoDb"]
}

model Post {
  id    String @id @default(auto()) @map("_id") @db.ObjectId
  slug  String @unique
  title String
  body  String
}

previewFeatures must be set to mongoDb in the client generator to enable MongoDB support.

Provision a MongoDB Database with Railway

There are two ways to setup a MongoDB database with Railway, through the dashboard or through the CLI.

Railway Dashboard

To use the dashboard, click dev.new and choose "Provision MongoDB."

After the database is setup click "MongoDB" on the left to see the default test database that is autogenerated.

Choose "Connect" to find your connection string.

Railway CLI

If you want to use the Railway CLI instead of the dashboard, first you need to install it. To verify that you successfully installed the CLI, run the following command to check the CLI version.



railway version

Run railway login to authenticate your Railway account. If you do not have a Railway account you will be prompted to create one.



railway login

railway init initializes a project and asks if you want to start with an empty project or a starter template. Select “Empty Project” and give your project a name.



railway init

Run railway add and select MongoDB to add the MongoDB plugin to your Railway project.



railway add

Connect Railway Database to Prisma Project

Return to the Railway dashboard to find your connection string.

Set Environment Variable

Inside your .env file include DATABASE_URL and set the variable to the connection string provided by Railway. Specify the database name and authentication source at the end of the connection string by adding /test?authSource=admin after the port number.



DATABASE_URL="mongodb://mongo:<PASSWORD>@containers-us-west-1.railway.app:6852/test?authSource=admin"

Sync the schema with the database by using prisma db push.



yarn prisma db push

Seed Database

You can also connect to the database directly with the mongosh command.



mongosh "mongodb://mongo:<PASSWORD>@containers-us-west-1.railway.app:6852"

The database can be seeded from the Railway dashboard or through mongosh with the following seed command.



db.Post.insertOne(
  {
    slug: "first-post-slug",
    title: "First Post Title",
    body: "First post body."
  }
)

Check the data tab in the Railway dashboard to see the data.

Generate Prisma Client

Generate the Prisma Client with the prisma generate command.



yarn prisma generate

Create a Script to Query the Database

Add the following script to index.js to test that we can read data from our database. This function runs the findMany query on our post collection and returns all posts in the collection.



// index.js

import pkg from '@prisma/client'

const { PrismaClient } = pkg
const prisma = new PrismaClient()

async function main() {
  await prisma.$connect()

  const posts = await prisma.post.findMany()

  console.dir(posts, { depth: Infinity })
}

main()
  .catch(console.error)
  .finally(() => prisma.$disconnect())

Run the Script

Run node index.js to execute the main function.



node index.js

If you followed along correctly you should get the following output:



[
  {
    id: '61f369df79160504b0ee41d9',
    slug: 'first-post-slug',
    title: 'First Post Title',
    body: 'First post body.'
  }
]

A First Look at Astro

ajcwebdev — Sun, 28 Nov 2021 01:14:57 +0000

Outline

Introduction
- Partial Hydration
- Client Directives
Create Project
- Install Astro Dependency
- Add CLI Commands
- Create a Page
- Start Development Server
- Add Styling
Add Components
- Create a Markdown Component
- Create a React Component
- Create a Svelte Component
- Create a Vue Component
- Create a GraphQL Data Fetching Component
Deploy to Netlify
- Create a GitHub Repository
- Connect GitHub Repository to Netlify

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

Astro is an open source web framework influenced by the Islands Architecture. It was created by Fred K. Schott, Matthew Phillips, Nate Moore, and Drew Powers as an outgrowth of the work being done simultaneously on Snowpack and Skypack.

It supports a variety of UI integrations including React, Svelte, Vue, Solid, and many more. The framework deserves a fair amount of credit for bringing partial hydration and the concept of "Islands of Interactivity" to the mainstream web development conversation.

Partial Hydration

I have an entirely separate, lengthy article about this, but here's the summary. The conversation had been present but on the fringes for well over a decade. The first framework that fully supported these techniques, Marko, was created in 2014 but remained the odd duck out until around 2019.

However, in the last 2 years there has been an influx of frameworks drawing on similar motivations and prior art including Slinkity, Elder.js, îles, and Qwik. Fred K. Schott describes the architecture and goals of Astro in Introducing Astro: Ship Less JavaScript (June 8, 2021):

Astro works a lot like a static site generator. If you have ever used Eleventy, Hugo, or Jekyll (or even a server-side web framework like Rails, Laravel, or Django) then you should feel right at home with Astro.

In Astro, you compose your website using UI components from your favorite JavaScript web framework (React, Svelte, Vue, etc). Astro renders your entire site to static HTML during the build. The result is a fully static website with all JavaScript removed from the final page.

While there are plenty of frameworks based on React, Vue, and Svelte that let you render components to static HTML during build time, if you want to hydrate these projects on the client then you have to ship an entire bundle of dependencies along with the static HTML. Astro, on the other hand, includes the ability to load just a single component and its dependencies where that component is needed.

Client Directives

Astro includes five client:* directives to hydrate components on the client at runtime. A directive is a component attribute that tells Astro how your component should be rendered.

Directive	Description
`<Component client:load />`	Hydrates the component on page load.
`<Component client:idle />`	Hydrates the component as soon as main thread is free.
`<Component client:visible />`	Hydrates the component as soon as the element enters the viewport.
`<Component client:media={QUERY} />`	Hydrates the component as soon as the browser matches the given media query.
`<Component client:only />`	Hydrates the component at page load, similar to `client:load`. The component will be skipped at build time.

Create Project

This tutorial will build up an Astro project from scratch instead of using any of the starter templates because I believe that is a better way to learn how a framework works, but the templates are really fantastic.

Start by creating a new directory for your project and initializing a package.json file.

mkdir ajcwebdev-astro
cd ajcwebdev-astro
yarn init -y

Install Astro Dependency

Install the astro dependency and create .gitignore file.

yarn add -D astro
echo 'node_modules\ndist\n.DS_Store' > .gitignore

Add CLI Commands

Add the following scripts to package.json.

{
  "name": "ajcwebdev-astro",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "astro": "^1.0.0-beta.28"
  },
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

All commands are run from the root of the project.

yarn dev and yarn start both start a local development server on localhost:3000.
yarn build builds a production site to ./dist.
yarn preview previews the build locally before deploying.

Create a Page

Astro looks for .astro or .md files in the src/pages directory. Each page is exposed as a route based on its file name. Static assets such as images can be placed in the public directory.

mkdir -p src/pages public
touch src/pages/index.astro

Inside the src/pages directory we created an index.astro file.

---
// src/pages/index.astro

let title = 'ajcwebdev-astro'
---

<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width">

    <title>{title}</title>
  </head>

  <body>
    <main>
      <header>
        <div>
          <h1>ajcwebdev-astro</h1>
        </div>

        <p>Hello! This is an example Astro project by Anthony Campolo (ajcwebdev).</p>
      </header>
    </main>

    <footer>
      <h3>Find me on the internet:</h3>

      <ul>
        <li><a href="https://ajcwebdev.com">Blog</a></li>
        <li><a href="https://github.com/ajcwebdev">GitHub</a></li>
        <li><a href="https://twitter.com/ajcwebdev">Twitter</a></li>
      </ul>
    </footer>
  </body>
</html>

Start Development Server

yarn dev

Open localhost:3000 to see the home page.

Add Styling

I'll include Water.css in the head of index.html for some nice looking CSS defaults.

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css">

  <title>{title}</title>
</head>

Add Components

We'll create a directory called components inside src to hold any Astro/React/Vue/Svelte/Preact components. Then we will create three extra directories that will hold .astro, .jsx, and .svelte files for Markdown, React, and Svelte components respectively.

Create a Markdown Component

The first example will use Markdown and render completely statically. Astro includes a built in Markdown component that can be imported into any .md file.

mkdir -p src/components/markdown
touch src/components/markdown/HelloMarkdown.astro

Import the Markdown component from astro/components and write some Markdown.

---
// src/components/markdown/HelloMarkdown.astro

import { Markdown } from 'astro/components'
---

<article>
  <section>
    <h2>Markdown</h2>

    <Markdown>
      ### This is an h3 with Markdown

      *Pretty* **cool**, ***right***?
    </Markdown>
  </section>
</article>

Return to index.astro and import HelloMarkdown from '../components/markdown/HelloMarkdown.astro'. Place <HelloMarkdown /> inside the main tags.

---
// src/pages/index.astro

import HelloMarkdown from '../components/markdown/HelloMarkdown.astro'

let title = 'ajcwebdev-astro'
---

<html lang="en">
  <head>...</head>
  <body>
    <main>
      <header>...</header>
    </main>

    <section>
      <HelloMarkdown />
    </section>
    <footer>...</footer>
  </body>
</html>

Create a React Component

To configure Astro, add an astro.config.mjs file and install the necessary React dependencies by running the following command:

yarn astro add react

This installs @astrojs/react, react-dom@^18.0.0, and react@^18.0.0. It also adds the following code to astro.config.mjs to enable the React renderer and provide support for React JSX components.

// astro.config.mjs

import { defineConfig } from 'astro/config'
import react from "@astrojs/react"

export default defineConfig({
  integrations: [react()]
})

We'll create a react directory with a HelloReact.jsx component inside.

mkdir src/components/react
touch src/components/react/HelloReact.jsx

It's a React component so you're contractually obligated to make it a counter with useState that is triggered with an onClick event handler on a <button>.

// src/components/react/HelloReact.jsx

import { useState } from 'react'

export default function HelloReact({ children, count: initialCount }) {
  const [count, setCount] = useState(initialCount)

  const add = () => setCount((i) => i + 1)
  const subtract = () => setCount((i) => i - 1)

  return (
    <>
      <h2>{children}</h2>

      <div style={{display:'flex'}}>
        <button onClick={subtract}>-</button>
        <pre>{count}</pre>
        <button onClick={add}>+</button>
      </div>
    </>
  )
}

Importing the HelloReact component is much like the HelloMarkdown component. However, this time we're including someProps in the front matter to set the initial count to 0.

---
// src/pages/index.astro

import HelloMarkdown from '../components/markdown/HelloMarkdown.astro'
import HelloReact from '../components/react/HelloReact.jsx'

const someProps = {
  count: 0,
}

let title = 'ajcwebdev-astro'
---

<html lang="en">
  <head>...</head>
  <body>
    <main>
      <header>...</header>

      <HelloReact {...someProps} client:visible>
        React
      </HelloReact>
    </main>

    <section>
      <HelloMarkdown />
    </section>
    <footer>...</footer>
  </body>
</html>

We also include client:visible to hydrate the component as soon as the element enters the viewport.

Create a Svelte Component

Add svelte() to integrations in astro.config.mjs to enable the Svelte renderer and provide support for Svelte components.

yarn astro add svelte

This also installs @astrojs/svelte and svelte@^3.46.4.

// astro.config.mjs

import { defineConfig } from 'astro/config'
import react from "@astrojs/react"
import svelte from "@astrojs/svelte"

export default defineConfig({
  integrations: [react(), svelte()]
})

As with React, create a svelte directory and HelloSvelte.svelte file.

mkdir src/components/svelte
touch src/components/svelte/HelloSvelte.svelte

Our Svelte component will contain the same functionality as our React component.

<!-- src/components/svelte/HelloSvelte.svelte -->

<script>
  let count = 0

  function add() {
    count += 1
  }

  function subtract() {
    count -= 1
  }
</script>

<h2><slot /></h2>

<div>
  <button on:click={subtract}>-</button>
  <pre>{ count }</pre>
  <button on:click={add}>+</button>
</div>

<style>
  div {
    display: flex;
  }
</style>

Import HelloSvelte and set it to client:visible.

---
// src/pages/index.astro

import HelloMarkdown from '../components/markdown/HelloMarkdown.astro'
import HelloReact from '../components/react/HelloReact.jsx'
import HelloSvelte from '../components/svelte/HelloSvelte.svelte'

const someProps = {
  count: 0,
}

let title = 'ajcwebdev-astro'
---

<html lang="en">
  <head>...</head>
  <body>
    <main>
      <header>...</header>

      <HelloReact {...someProps} client:visible>
        React
      </HelloReact>

      <HelloSvelte client:visible>
        Svelte
      </HelloSvelte>
    </main>

    <section>
      <HelloMarkdown />
    </section>
    <footer>...</footer>
  </body>
</html>

Create a Vue Component

Add vue() to integrations in astro.config.mjs to enable the Vue renderer.

yarn astro add vue

This also install @astrojs/vue and vue@^3.2.30.

// astro.config.mjs

import { defineConfig } from 'astro/config'
import react from "@astrojs/react"
import svelte from "@astrojs/svelte"
import vue from "@astrojs/vue"

export default defineConfig({
  integrations: [react(), svelte(), vue()]
})

You know the drill.

mkdir src/components/vue
touch src/components/vue/HelloVue.vue

Our Vue component will contain the same functionality as our React and Svelte components.

<!-- src/components/vue/HelloVue.vue -->

<template>
  <h2><slot /></h2>

  <div>
    <button @click="subtract()">-</button>
    <pre>{{ count }}</pre>
    <button @click="add()">+</button>
  </div>
</template>

<script>
  import { ref } from 'vue'

  export default {
    setup() {
      const count = ref(0)
      const add = () => (count.value = count.value + 1)
      const subtract = () => (count.value = count.value - 1)

      return {
        count, add, subtract,
      }
    },
  }
</script>

<style scoped>
  div {
    display: flex;
  }
</style>

Import HelloVue and set it to client:visible.

---
// src/pages/index.astro

import HelloMarkdown from '../components/markdown/HelloMarkdown.astro'
import HelloReact from '../components/react/HelloReact.jsx'
import HelloSvelte from '../components/svelte/HelloSvelte.svelte'
import HelloVue from '../components/vue/HelloVue.vue'

const someProps = {
  count: 0,
}

let title = 'ajcwebdev-astro'
---

<html lang="en">
  <head>...</head>
  <body>
    <main>
      <header>...</header>

      <HelloReact {...someProps} client:visible>
        React
      </HelloReact>

      <HelloSvelte client:visible>
        Svelte
      </HelloSvelte>

      <HelloVue client:visible>
        Vue
      </HelloVue>
    </main>

    <section>
      <HelloMarkdown />
    </section>
    <footer>...</footer>
  </body>
</html>

Create a GraphQL Data Fetching Component

mkdir src/components/graphql
touch src/components/graphql/HelloGraphQL.astro src/pages/graphql.astro

---
// src/components/graphql/HelloGraphQL.astro

const res = await fetch('https://rickandmortyapi.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `{
      characters {
        results {
          name
        }
      }
    }`
  })
})

const { data } = await res.json()
const { characters } = data
---

<h2>Rick and Morty GraphQL API</h2>

<ul>
  {characters.results.map(({ name }) => (
    <li>{name}</li>
  ))}
</ul>

Import HelloGraphQL.

---
// src/pages/graphql.astro

import HelloGraphQL from '../components/graphql/HelloGraphQL.astro'

let title = 'GraphQL'
---

<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css">

    <title>{title}</title>
  </head>

  <body>
    <main>
      <HelloGraphQL />
    </main>
  </body>
</html>

Deploy to Netlify

The Astro docs contain over a dozen different deployment options. We will deploy our project to Netlify. Create a netlify.toml file for our build configuration.

touch netlify.toml

Add yarn build for the build command and dist for the publish directory.

[build]
  command = "yarn build"
  publish = "dist"

Here is our final project structure.

/
├── public
├── src
│   ├── components
│   │   ├── graphql
│   │   │   └── HelloGraphQL.astro
│   │   ├── markdown
│   │   │   └── HelloMarkdown.astro
│   │   ├── react
│   │   │   └── HelloReact.jsx
│   │   ├── svelte
│   │   │   └── HelloSvelte.svelte
│   │   └── vue
│   │       └── HelloVue.vue
│   └── pages
│       ├── graphql.astro
│       └── index.astro
├── .gitignore
├── astro.config.mjs
├── netlify.toml
└── package.json

Create a GitHub Repository

Initialize a git repo and push to a GitHub repository.

git init
git add .
git commit -m "svuereactroQL"
gh repo create ajcwebdev-astro --public --push \
  --source=. \
  --description="Example Astro project with Markdown, React, Svelte, and Vue" \
  --remote=upstream

Connect GitHub Repository to Netlify

Connect your GitHub repository to Netlify.

Go to "Site settings," to give yourself a custom domain name.

Open ajcwebdev-astro.netlify.app to see the deployed site.

What's Partial Hydration and Why's Everyone Talking About It?

ajcwebdev — Mon, 22 Nov 2021 18:12:13 +0000

In The Cost Of Client-side Rehydration (February 8, 2019), Addy Osmani argued that:

Server rendering a page and then rehydrating DOM client-side through a serialized version of a UI's dependencies (rehydration) can come with a real cost. It can heavily delay Time To Interactive by making UI look ready before client-side processing has completed.

He wondered if the benefits of rehydration were outweighed by the Uncanny Valley that is created for users by painting pixels early. To illustrate this point, he created the following graphic:

Outline

To Hydrate or Not to Hydrate
- Partial Hydration and Progressive Rehydration
- Islands of Interactivity
Adding Partial Hydration to Existing Frameworks
- React
- Preact
- Vue
- Solid
- Svelte
Frameworks Built for Partial Hydration
- Marko
- Elder.js
- Astro
- Slinkity
- îles
- Qwik
Conclusion

To Hydrate or Not to Hydrate

Hydration (or rehydration) is a technique that uses client-side JavaScript to convert static HTML pages into dynamic web pages by attaching event handlers to the HTML elements. The JavaScript can be delivered either through static hosting or server-side rendering.

Partial Hydration and Progressive Rehydration

Partial rehydration is an extension of the idea of progressive rehydration where individual pieces of a server-rendered application are “booted up” over time. This contrasts with the approach of initializing the entire application at once. In an attempt to systematically define and compare the different commonly used rendering and hydration techniques, Addy Osmani and Jason Miller published Rendering on the Web (February 6, 2019):

Partial rehydration has proven difficult to implement. This approach is an extension of the idea of progressive rehydration, where the individual pieces (components / views / trees) to be progressively rehydrated are analyzed and those with little interactivity or no reactivity are identified.

For each of these mostly-static parts, the corresponding JavaScript code is then transformed into inert references and decorative functionality, reducing their client-side footprint to near-zero.

Sounds great! But like all things in tech, nothing is a silver bullet (especially since silver bullets only work on werewolf shaped problems anyway).

The partial hydration approach comes with its own issues and compromises. It poses some interesting challenges for caching, and client-side navigation means we can't assume server-rendered HTML for inert parts of the application will be available without a full page load.

To summarize the points of the article, the authors included this behemoth of a comparison table:

But this table isn't the whole story, as Jason Miller noted on Twitter:

One thing I want to clarify: the diagram in this tweet doesn't tell the full story, and doesn't show SSR+Hydration with possible optimizations like component caching applied.

To expand on this view point, Mike Sherov argued:

The chart talks about Time to First Byte and Time to Interactive relative to First Contentful Paint, but not First Contentful Paint relative to Time to First Byte... so it misses out on that positive fact that SSR solutions will render faster. The chart assumes that “SSR with (re)hydration” doesn’t employ a “JavaScript as progressive enhancement”... that is, it assumes the page is only functional after all JavaScript is delivered

Next.js and others encourage JavaScript as progressive enhancement so that Time to Interactive equals First Contentful Paint still. As mentioned in the disclaimer tweet, this ignores CDN caching of SSR HTML, but ignoring it significantly changes the value prop of “SSR with JavaScript as progressive enhancement”. CDN caching of HTML is flexible AND has high Time to First Byte.

Islands of Interactivity

While continuing to explore this problem space, Jason Miller coined the term Islands Architecture (August 11, 2020) in reference to the "Component Islands" pattern advocated by Katie Sylor-Miller. He believed web developers should aim to create "islands of interactivity" with JavaScript carefully selected for inclusion only when necessary.

In an "islands" model, server rendering is not a bolt-on optimization aimed at improving SEO or UX. Instead, it is a fundamental part of how pages are delivered to the browser. The HTML returned in response to navigation contains a meaningful and immediately renderable representation of the content the user requested.

Does this mean that partial hydration and the Island's Architecture are interchangeable, or that partial hydration is an implementation of the Island's Architecture? Not exactly. According to Ryan Carniato in Is 0kb of JavaScript in your Future? (May 3, 2021), partial hydration is a lot like the Island's architecture because the end result is Islands of interactivity but the difference is the authoring experience.

Instead of authoring a static layer and an Island's layer, you write your code like a single app more like a typical frontend framework. Partial hydration automatically can create the islands for you to ship the minimal code to the browser. Marko is a JavaScript library that uses its compiler to automate this partial hydration process to remove Server only rendered components from the browser bundle.

Adding Partial Hydration to Existing Frameworks

Despite the growing awareness throughout 2019 and 2020 of the difficulties of hydration and the need for some form of partial hydration, we can find discussions of the topic much earlier. Paul Lewis described three different levels of hydration (which he called "booting models") in his blog post, When everything's important, nothing is! (December 10, 2016).

Early attempts at this were made by Angular and Ember. These attempts appear to have struggled to gain traction. The relevant Angular issue is currently still open 5 years later and Brian Cardarella argued in Should you use Ember FastBoot or not? (August 1, 2017) that the costs were too high for DockYard to implement FastBoot.

React

The release of React v16.0 in September 2017 introduced the hydrate() method as an alternative to the render() method. According to Andrew Clark:

React 16 is better at hydrating server-rendered HTML once it reaches the client. It no longer requires the initial render to exactly match the result from the server. Instead, it will attempt to reuse as much of the existing DOM as possible. No more checksums!

hydrate() behaves similarly to the render() method. However, instead of rendering a React element into the DOM in the supplied container and returning a reference to the component, hydrate() can hydrate a container whose HTML contents are rendered by ReactDOMServer and attempt to attach event listeners to the existing markup.

To balance this trade off, developers were advised to use render() for rendering the content solely on the client side and hydrate() for rendering on top of server-side rendered markup. Much like the Google team, the React team urged caution when deciding whether to use hydration:

In general, we don’t recommend that you render different content on the client versus the server, but it can be useful in some cases (e.g. timestamps). However, it’s dangerous to have missing nodes on the server render as this might cause sibling nodes to be created with incorrect attributes.

Two years later, Sebastian Markbåge opened a PR to implement Partial Hydration (January 28, 2019) as a native feature in React:

Partial hydration adds a mechanism for partially hydrating a server rendered result while other parts of the page are still loading the code or data. This means that you can start interacting with parts of the screen while others are still hydrating. In this model you always have to hydrate the root content first because it is what provides props to the children, which can be of arbitrary complexity.

The model assumes that the root of the app is designed to be relatively shallow and then each abstraction gets progressively more complex the deeper it gets. To become interactive faster, components in the tree can themselves use progressive enhancement to add more complexity after initial hydration.

Preact

Markus Oberlehner foreshadows Slinkity (discussed more in a later section) by explaining how to combine the static site generator Eleventy with Preact in Building Partially Hydrated, Progressively Enhanced Static Websites with Isomorphic Preact and Eleventy (March 22, 2020):

What if I tell you that we can have it all? We can use a modern JavaScript framework, at least as powerful as React, combine it with an exceptional static site generator, and build our websites in a way that they offer real progressive enhancement and a minimal JavaScript bundle size. Combining Eleventy with Preact makes this possible.

Vue

Based on his work porting vue-lazy-hydration to Vue 3, Markus Oberlehner compares different forms of partial hydration in Partial Hydration Concepts: Lazy and Active (November 8, 2020):

Lazy Hydration is a form of Partial Hydration where you can trigger hydration at a later point and not immediately after loading the site. A good example is components outside of the viewport. You don’t need to hydrate them instantly, but you can delay hydration until the component is visible.

<template>
  <TheNavigation/>

  <LazyHydrate skip>
    <TheBlogArticle/>
  </LazyHydrate>

  <LazyHydrate when-visible>
    <TheFooter/>
  </LazyHydrate>
</template>

The Lazy Hydration concept you can see above works best when we have a mostly interactive application, but we want to exclude some parts from the hydration. Let’s imagine the other way around: we have a huge application with deeply nested components, it is a static website, but there is this one deeply nested component, which must be interactive.

<template>
  <LazyHydrate skip>
    <App/>
  </LazyHydrate>
</template>

Solid

Ryan Carniato, taking influence from Marko (discussed more in a later section), proposes using sub-component (or component-level) hydration in Partial Hydration (November 15, 2020).

This is the last core feature missing in our SSR story. Truth be told outside of Marko most libraries aren't doing amazing here. We can too consider a more manual approach here at first. I think the key innovation would be to follow Marko's footsteps and recognize there in fact 3 partial hydration modes rather than 2 other libraries are aware of. There is a middle mode that make us considerably more efficient at this. This is uniquely possible given the granular non-component tied approach used here.

Svelte

According to Rich Harris in March 2021, partial hydration is on Svelte's radar but not yet on its roadmap. This makes sense since Svelte is already compiling an optimized build of vanilla JavaScript that does not require a runtime. However, Kevin Åberg Kultalahti proposed Partial Hydration in Svelte (May 9, 2021) via the use:action directive. We will also see in the next section that a Svelte metaframework, Elder.js, has struck out on its own to implement partial hydration.

Frameworks Built for Partial Hydration

As we can see, essentially every major frontend JavaScript framework has attempted to add some form of partial hydration with varying degrees of success. But there is another category entirely of frontend frameworks that consider partial hydration a key feature to be included from their inception.

Marko

If there is one framework that can be given credit for first introducing partial hydration as a primary feature (even before the term was invented), my money would be on Marko. Patrick Steele-Idem discussed Marko's internals at length in Async Fragments: Rediscovering Progressive HTML Rendering with Marko (December 8, 2014). He also includes a wealth of links to prior art such as:

The Lost Art of Progressive HTML Rendering (November 14, 2005) by Jeff Atwood.
Best Practices for Speeding Up Your Web Site (December 12, 2006) by Yahoo's Exceptional Performance Team (epic team name).
Progressive rendering via multiple flushes (December 21, 2009) by Stoyan Stefanov.
BigPipe: Pipelining web pages for high performance (June 4, 2010) by Changhao Jiang.

Michael Rawlings takes a look at Marko's innovations from the perspective of the last few years in Maybe you don’t need that SPA (May 12, 2020):

Marko allows you to build pages by composing components and some of these components can be stateful. Only those components that have state, or other logic targeted at the browser are actually sent to the browser and Marko automatically handles serializing any data from the server needed by these components and mounting them in the browser.

This means for most apps, you end up sending down much less code than you would for an equivalent SPA — even with code-splitting. And if no components need to be hydrated? Nothing is hydrated.

Elder.js

Despite Svelte core choosing to hold off on focusing on partial hydration throughout 2020-2021, one of the early entrants into the race for partial hydration leadership was Elder.js by Nick Reese, a static site generator built with Svelte. Focused primarily on SEO, Elder.js lets you hydrate just the parts of the client that need to be interactive.

This lets you reduce your payloads while still having control over component lazy-loading, preloading, and eager-loading. While lesser known than Astro, Elder.js included partial hydration as early as August 2020, roughly six months before Astro's initial commit.

<div class="right">
  <Clock hydrate-client={{}} />
</div>

Astro

Despite the early innovations of Marko and Elder, the framework that deserves the most credit for bringing partial hydration to the mainstream is Astro. Fred K. Schott describes the architecture and goals of Astro in Introducing Astro: Ship Less JavaScript (June 8, 2021).

Astro works a lot like a static site generator. If you have ever used Eleventy, Hugo, or Jekyll (or even a server-side web framework like Rails, Laravel, or Django) then you should feel right at home with Astro.

In Astro, you compose your website using UI components from your favorite JavaScript web framework (React, Svelte, Vue, etc). Astro renders your entire site to static HTML during the build. The result is a fully static website with all JavaScript removed from the final page.

There are already plenty of frameworks based on React, Vue, and Svelte that include the ability to render your components to static HTML during build time. However, if you want to hydrate these projects on the client then you have to ship an entire bundle of dependencies along with the static HTML. Unlike these previous frameworks, Astro includes the ability to load just a single component and its dependencies where that component is needed.

Of course, sometimes client-side JavaScript is inevitable for things like image carousels, shopping carts, and auto-complete search bars. This is where Astro really shines: When a component needs some JavaScript, Astro only loads that one component (and any dependencies). The rest of your site continues to exist as static, lightweight HTML.

In Astro, this kind of partial hydration is built into the tool itself. You can even automatically defer components to only load once they become visible on the page with the :visible modifier. This new approach to web architecture is called islands architecture.

Astro includes five client:* directives to hydrate components on the client at runtime. A directive is a component attribute that tells Astro how your component should be rendered.

<MyComponent client:load /> - Hydrate the component on page load.
<MyComponent client:idle /> - Hydrate the component as soon as main thread is free.
<MyComponent client:visible /> - Hydrate the component as soon as the element enters the viewport. Useful for content lower down on the page.
<MyComponent client:media={QUERY} /> - Hydrate the component as soon as the browser matches the given media query. Useful for sidebar toggles, or other elements that should only display on mobile or desktop devices.
<MyComponent client:only /> - Hydrates the component at page load, similar to client:load. The component will be skipped at build time, useful for components that are entirely dependent on client-side APIs. Best avoided unless absolutely needed.

The following example is hydrating a React component (MyReactComponent) in the browser with client:visible. client:visible means the component won't load any client-side JavaScript until it becomes visible in the user's browser.

---
import MyReactComponent from '../components/MyReactComponent.jsx';
---

<MyReactComponent client:visible />

Slinkity

Slinkity is a framework that uses Vite to bring dynamic, client side interactions to your static 11ty sites with partial hydration. In Ship JavaScript where it counts with Vite + Partial Hydration (November 12, 2021), Ben Holmes makes the case for turning off partial hydration by default so the developer has to explicitly opt-in:

Right now, the Jamstack landscape definitely relies on an opt-out mindset. Too much JavaScript on initial page load? Opt-out with code splitting and lazy ESM loading. Need less JavaScript on your company’s splash page? Opt-out with server-rendered components. The world of partial hydration introduced by Astro, Slinkity + 11ty, or Îles flips that opt-out to an opt-in.

Too much JavaScript on initial page load? Well, you’ll need to opt-in to JavaScript hydration for your UI components to create that problem! These frameworks default to no JavaScript shipped for your React, Vue, Svelte, etc, with hydration “modes” to decide how and when those resources should be loaded (if at all).

To choose how a given component is rendered, you'll need to pass a render prop, as in a prop literally named render.

export const frontMatter = {
  render: 'eager';
}

function Page() {...}

Alternatively, you can use a shortcode that includes render and the hydration option you want to select. The default for all components is eager to mirror how previous component-based frameworks operate.

<!-- page-with-shortcode.html -->

<body>
  {% react 'components/Example' 'render' 'eager' %}
</body>

A component loaded with eager will be rendered to static HTML, and shipped to the client as a JavaScript bundle. In the previous example, visiting page-with-shortcode.html imports React and the components/Example.jsx JavaScript bundle as soon as the page is done parsing, ensuring our component is interactive as soon as possible.
lazy is similar to eager except it only loads your component's JavaScript when your component is scrolled into view by using the Intersection Observer API.
static components are rendered to HTML at build time and don't ship any JavaScript to the client, meaning no interactivity or state management. This is useful if you want to use component languages like React as just a templating language.

îles

îles is a static-site generator that provides automatic partial hydration. The name of the project is French for "islands," as a clever homage to both the islands architecture and it's build tool Vite. Inspired by Astro, you are able to define which components should remain interactive in the production build with client: directives in components. Here is an example with MDX:

---
audio: /song-for-you.mp3
---

## Play a song

<AudioPlayer {...frontmatter} client:visible/>

Components in the src/components directory are auto-imported on demand, which is why the example above does not need to import the AudioPlayer component. You can also use directives inside Vue components as seen in the following example:

<Audio client:visible :src="audio" :initialDuration="initialDuration"/>

Qwik

Qwik focuses on resumability of server-side-rendering of HTML and fine-grained lazy-loading of code. It is designed for the best possible time to interactive. According to Miško Hevery in A First Look at Qwik - The HTML First Framework (June 23, 2021):

The basic goal of Qwik is to focus on the time-to-interactive metric by delaying JavaScript as much as possible to take advantage of the browser’s lazy loading capabilities. This is in stark contrast to existing frameworks that treat server-side-rendering and time-to-interactive more as an afterthought rather than a primary goal, which drives all other design decisions.

With Qwik we now have a framework explicitly aiming to prioritize Time to Interactive which it does through resumability. But what does it mean to be resumable?

The basic idea behind Qwik is that it is resumable. It can continue where the server left off. There is but the tiniest amount of code to execute on the client. The qwikloader, which takes the static HTML generated from server-side-rendering and resumes it, is less than 1kb and will execute in under 1ms... All the other interactivity of your website is downloaded lazily as you interact with the site in the smallest possible chunks.

Qwik also rehydrates components asynchronously and out of order to ensure that the first interaction does not cause a full application download and bootstrap.

Here asynchronously means that the rendering system can pause rendering to asynchronously download a template for a component, and then continue the rendering process. This is in stark contrast to all of the existing frameworks, which have fully synchronous rendering pipelines. And because the rendering is synchronous, there is no place to insert asynchronous lazy-loading. The consequence is that all of the templates need to be present ahead of call to render.

Ryan Carniato had this to say about Qwik:

It's the only framework that goes from shipping basically only the JavaScript you need on a page (starting maybe even from 0kb), to being able to go full SPA. It can actually with out of order lazy hydration bring in client routing after the fact.

It is the only framework that I know of today that basically operates as Islands but can morph into a single application as needed. This is coming to Marko and probably others but we shouldn't get ahead of ourselves. And it's a longer road for traditional SPAs.

Conclusion

Frameworks like Qwik bring us full circle from Addy Osmani's warning to developers that slow Time to Interactive scores can cause an uncanny valley effect. Websites ship skeleton HTML that looks like it should be interactive but momentarily is not because the user has to wait for the client to hydrate.

But as this article demonstrates, as soon as developers are given the ability to configure these parameters they find themselves in a complex decision matrix of trade offs. The next evolution will involve taking these performance advantages and designing conventions to simplify these techniques and create happy paths in the frameworks that developers are already comfortable using.

Special thanks to Ryan Carniato for early feedback on the post and Ben Holmes for chatting with me for literally months about this stuff.

How to Display a Custom Daily Greeting

ajcwebdev — Thu, 11 Nov 2021 01:46:36 +0000

Introduction

I discovered a cool little trick while source diving through Scott Mathson's web site. With just a couple lines of JavaScript you can create a message that displays a different greeting depending on the day of the week.

Create a Script with a Weekday Array

Create a <script> tag with type of text/javascript. Define a variable called weekday with a different greeting set to each index.

<script type="text/javascript">

  var weekday = new Array(7)

  weekday[0] = "spectacular Sunday"
  weekday[1] = "marvelous Monday"
  weekday[2] = "terrific Tuesday"
  weekday[3] = "wonderful Wednesday"
  weekday[4] = "totally cool Thursday"
  weekday[5] = "fantastic Friday"
  weekday[6] = "sweet Saturday"

</script>

Set Weekday Value to the Current Date

Also inside the script tag, create a variable called currentDate set with the Date() object and then set the current day to weekdayValue.

var currentDate = new Date()
weekdayValue = currentDate.getDay()

Write to the Document

Use the Document.write() method to write a string of text to the document with paragraph tags containing the weekday value..

document.write(
  '<p>Have a ' + weekday[weekdayValue] + '!</p>'
)

Noscript Fallback

Lastly, you'll want to include a <noscript> tag in case the user has JavaScript turned off in their browser.

<noscript>
  <p>Have a great day!</p>
</noscript>

Full Script

<script type="text/javascript">

  var weekday = new Array(7)

  weekday[0] = "spectacular Sunday"
  weekday[1] = "marvelous Monday"
  weekday[2] = "terrific Tuesday"
  weekday[3] = "wonderful Wednesday"
  weekday[4] = "totally cool Thursday"
  weekday[5] = "fantastic Friday"
  weekday[6] = "sweet Saturday"

  var currentDate = new Date()
  weekdayValue = currentDate.getDay()

  document.write(
    '<p>Have a ' + weekday[weekdayValue] + '!</p>'
  )
</script>

<noscript>
  <p>Have a great day!</p>
</noscript>

A First Look at Oak

ajcwebdev — Tue, 02 Nov 2021 14:47:43 +0000

Outline

Introduction
Setup
- Install Deno Executable
- Install deployctl
- Create Project Files
Create Deno Server
- Run Deno Server
Create Oak Server
- Application Class
- Respond with HTML
- Add Router
Deno Deploy
- Run Oak Server with deployctl
- Initialize GitHub Repository
- Install the Deno Deploy GitHub App
- Sign Up for Deno Deploy
- Create Deno Deploy Project
- Connect GitHub Repository

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

Oak is a middleware framework for Deno's native HTTP server and Deno Deploy. It is influenced by Koa (hence the anagram) and includes a middleware router inspired by @koa/router.

Setup

Deno ships as a single executable with no dependencies. However, we will also need to install deployctl for Deno Deploy.

Install Deno Executable

There are various ways of installing Deno depending on your operating system. If you are using Mac or Linux, the official Shell install script is recommend.

curl -fsSL https://deno.land/x/install/install.sh | sh

You can find a list of different installation methods on the official deno.land documentation and the deno_install repo.

Install deployctl

With deployctl you can run your Deno Deploy scripts on your local machine. Your scripts are run in the Deno CLI, with the correct TypeScript types for Deno Deploy. After installing Deno, deployctl can be installed using the following command.

deno install \
  --allow-read \
  --allow-write \
  --allow-env \
  --allow-net \
  --allow-run \
  --no-check \
  --force \
  https://deno.land/x/deploy/deployctl.ts

You may need to set the PATH variable as seen below but with your own path to the deno executable in place of /Users/ajcwebdev.

export PATH="/Users/ajcwebdev/.deno/bin:$PATH"

Create Project Files

All we need is a directory containing an index.js file.

mkdir ajcwebdev-oak
cd ajcwebdev-oak
touch index.js
echo '.DS_Store' > .gitignore

Create Deno Server

Before diving into Oak, it's useful to see the underlying server code they are building upon. The Deno Standard Library has an http module with a basic hello world application. Save the following code in index.js:

// index.js

import { listenAndServe } from "https://deno.land/[email protected]/http/server.ts"

listenAndServe(
  ":8080",
  () => new Response("Hello from Deno on Localhost 8080")
)

console.log("Server running on localhost:8080")

Run Deno Server

deno run \
  --allow-net index.js \
  --watch \
  --no-check

Server running on localhost:8080

Open localhost:8080.

Create Oak Server

Oak is a third party module for Deno hosted on their deno.land/x service. To import one of these modules, use the following format for code URLs:

https://deno.land/x/IDENTIFIER@VERSION/FILE_PATH

If you leave out the version it will default to the most recent version released for the module. The Deno docs recommend pinning to a specific version to avoid unexpected breaking changes. At the time of this writing, the current version of Oak is https://deno.land/x/[email protected]/mod.ts.

Application Class

The Application class coordinates managing the HTTP server, running middleware, and handling errors that occur when processing requests. Two methods are generally used:

Middleware is added via the .use() method.
The .listen() method starts the server and then processes requests with the registered middleware.

Once the server is open, before it starts processing requests, the application will fire a "listen" event, which can be listened for via the .addEventListener() method.

// index.js

import { Application } from "https://deno.land/x/[email protected]/mod.ts"

const app = new Application()

app.use((ctx) => {
  ctx.response.body = "Hello from Oak on Localhost 8080"
})

app.addEventListener('listen', () => {
  console.log(`Server running on localhost:8080`)
})

app.listen({ port: 8080 })

The middleware is processed as a stack, where each middleware function can control the flow of the response. When the middleware is called, it is passed a context (ctx) and reference to the "next" method in the stack.

.response accesses the Response object to form the response sent back to the requestor.
The .body method returns a representation of the request body.

Return to localhost:8080.

Respond with HTML

To respond with HTML instead of plain text, use .headers.set on ctx.response and set the Content-Type to text/html.

// index.js

import { Application } from "https://deno.land/x/[email protected]/mod.ts"

const app = new Application()

app.use((ctx) => {
  ctx.response.body = "<h2>Hello from Oak on Localhost 8080</h2>"
  ctx.response.headers.set("Content-Type", "text/html")
})

app.addEventListener('listen', () => {
  console.log(`Server running on localhost:8080`)
})

app.listen({ port: 8080 })

Return to localhost:8080 to see the change.

Add Router

The Router class produces middleware which can be used with an Application to enable routing based on the pathname of the request.

// index.js

import { Application, Router } from "https://deno.land/x/[email protected]/mod.ts"

const router = new Router()
const app = new Application()

router.get("/", (ctx) => {
  ctx.response.body = "<h2>Hello from Router on Localhost 8080</h2>"
  ctx.response.headers.set("Content-Type", "text/html")
})

router.get("/about", (ctx) => {
  ctx.response.body = "<h2>This page tells you about stuff</h2>"
  ctx.response.headers.set("Content-Type", "text/html")
})

app.use(router.routes())
app.use(router.allowedMethods())

app.addEventListener('listen', () => {
  console.log(`Server running on localhost:8080`)
})

app.listen({ port: 8080 })

Return to localhost:8080 to see the change.

Open localhost:8080/about to see the new about page.

Deno Deploy

Deno Deploy is a distributed system that runs JavaScript, TypeScript, and WebAssembly at the edge, worldwide. It is a multi-tenant JavaScript engine running in 25 data centers across the world.

Run Oak Server with deployctl

You can run your script like it would run on Deno Deploy with deployctl. Include --no-check so TypeScript doesn't explode in a giant fireball of errors. You can also add the --watch flag to automatically restart the script when any modules in the module graph change.

deployctl run index.js --no-check --watch

If you return to localhost:8080 there will be no change in the application.

Initialize GitHub Repository

git init
git add .
git commit -m "finally, another project named after a tree"
gh repo create ajcwebdev-oak
git push -u origin main

Install the Deno Deploy GitHub App

We will be deploying this script from a URL on GitHub. Install the Deno Deploy GitHub App.

Sign Up for Deno Deploy

Create Deno Deploy Project

Click "New Project" and enter a name for your project.

After creating your project you are given the option of using existing templates.

Connect GitHub Repository

Since we will not be using a template, scroll down to connect the GitHub repository we just created.

Paste the raw GitHub URL for your function.

Click "Link" and go to ajcwebdev-oak.deno.dev.

You can use the project overview page to review your project's settings, add/remove domains, or view the deployment logs.

A First Look at Nuxt 3

ajcwebdev — Fri, 15 Oct 2021 08:03:36 +0000

Outline

Introduction
- Migrating from Nuxt 2 to Nuxt 3
- Try Online Example
Create Nuxt 3 Project from Scratch
- App Component
- Project Scripts
- Start Development Server
- Build for Production
- Pages Directory
Server Engine
- Server Directory for API Routes
Deployment
- Deploy to Vercel
- Deploy to Netlify

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

Nuxt is a Vue metaframework that aims to make web development intuitive and performant while keeping great developer experience in mind. The original version, created by Sébastien Chopin in October 2016, was built to emulate the features of Next.js (such as file-system based routing, server-side rendering, and API routes) but with Vue instead of React. Version 3 has been over a year in the making.

We are excited to open source Nuxt 3 after more than a year of intense development. On top of supporting Vue 3 and Vite, Nuxt 3 contains a new server engine, unlocking new full-stack capabilities to Nuxt server and beyond.

Introducing Nuxt 3 Beta

Nuxt 3 is composed of the following core packages:

Package	Purpose
nuxt3	Core Engine
nuxi	Command line interface
vite-builder or webpack-builder	Bundlers
nitro	Server engine
kit	Development kit
bridge	Nuxt 2 Bridge

Together these packages provide a selection of libraries for managing many common concerns for developers building on the web today such as:

Library	Common Concern
Vue.js	JavaScript framework for reactivity and components
Vite or Webpack 5	Bundler for hot module replacement in dev and bundling for production
esbuild	Transpiler for supporting legacy browsers while still using current JavaScript syntax
h3	Server that can serve your application in development and support server-side rendering or API routes
vue-router	Routing library to handle client-side navigation

In addition to curating and integrating these tools, Nuxt also provides directory structure conventions for managing pages and components.

Migrating from Nuxt 2 to Nuxt 3

Note: If you don't have a Nuxt 2 project, skip ahead to the section, "Create Nuxt 3 Project from Scratch."

The team has created two migration guides and tooling in the form of Nuxt Bridge to make migrating as smooth as possible . If you have an existing Nuxt 2 project, the team strongly recommends you begin by using Nuxt Bridge to experiment with new features while avoiding breaking changes. Bridge is a forward-compatibility layer that allows you to experience new Nuxt 3 features by installing and enabling a Nuxt module.

All Nuxt 2 modules should be forward compatible with Nuxt 3 as long as they migrate to bridge or if they are already following guidelines. All (upcoming) modules made with @nuxt/kit should be backward compatible with Nuxt 2 projects (even without bridge) as long as they are not depending on a Nuxt 3 / Bridge-only feature. Since Nuxt 3 natively supports TypeScript and ECMAScript Modules, it is useful to avoid CommonJS syntax such as __dirname, __filename, require(), and module.exports as much as possible.

Try Online Example

We will be building a Nuxt application from scratch. However, you can start playing with Nuxt 3 online in your browser on either StackBlitz or CodeSandBox.

Create Nuxt 3 Project from Scratch

Create a blank new directory and initialize a package.json file for defining our scripts and dependencies.

mkdir ajcwebdev-nuxt3
cd ajcwebdev-nuxt3
yarn init -y
yarn add -D [email protected] vercel

Version is current as of June 10, 2022, check the release schedule on GitHub for most recent version.

The project will start with only two additional files:

app.vue to display our Vue application
.gitignore to avoid accidentally committing stuff that shouldn't be committed

echo > app.vue
echo 'node_modules\n.DS_Store\n*.log\n.nuxt\nnuxt.d.ts\n.output' > .gitignore

We will create a directory for pages and an api later on.

App Component

app.vue is the main component in your Nuxt 3 applications. This means that anything you add to this file (such as JavaScript or CSS) will be global and included in every page.

<!-- app.vue -->

<template>
  <div>
    <h2>ajcwebdev-nuxt3</h2>
  </div>
</template>

With Nuxt 3, the pages directory is optional. If a pages directory is not present, Nuxt won't include the vue-router dependency. This is useful when working on single landing pages or other applications that don't not need routing.

Project Scripts

In your package.json, add the following scripts (build, dev, generate, and preview).

{
  "name": "ajcwebdev-nuxt3",
  "license": "MIT",
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview"
  },
  "devDependencies": {
    "nuxt": "3.0.0-rc.3",
    "vercel": "^25.1.0"
  }
}

Nuxi is the new CLI for Nuxt 3 and has four main commands:

dev - Start development server
build - Make production assets
generate - Generate static site
preview - Preview production build

Start Development Server

The yarn dev command starts your Nuxt app in development mode and includes hot module replacement. Include the --open flag to automatically open the browser after starting up.

yarn dev

The CLI will display links to the running application and performance metrics.

Nuxt CLI v3.0.0-rc.3

  > Local:    http://localhost:3000/
  > Network:  http://192.168.1.78:3000/

ℹ Vite client warmed up in 288ms
ℹ Vite server warmed up in 50ms
✔ Vite server built in 269ms
✔ Nitro built in 171 ms

Open localhost:3000 to see your application.

Build for Production

The yarn build command builds your Nuxt application for production. It creates a .output directory with your application, server, and dependencies ready to be deployed.

yarn build

Nitro produces a standalone server dist that is independent of node_modules. The output is combined with both runtime code to run your Nuxt server in any environment and serve you static files.

Pages Directory

The pages directory is optional, meaning that if you only use app.vue, vue-router won't be included, reducing your application bundle size. However, if you do include it, Nuxt will automatically integrate Vue Router and map the files in the pages directory into the routes of your application. Delete app.vue and create two files in a new pages directory.

rm -rf app.vue
mkdir pages
echo > pages/about.vue
echo > pages/index.vue

Include the previous home page's content in pages/index.vue.

<!-- pages/index.vue -->

<template>
  <div>
    <h2>ajcwebdev-nuxt3</h2>
  </div>
</template>

We also created pages/about.vue for an about page. Include the following code to make sure that people know stuff about your things.

<!-- pages/about.vue -->

<template>
  <div>
    <h2>This page tells you stuff about things!</h2>
  </div>
</template>

Open localhost:3000/about to see the about page.

Server Engine

Nuxt 3 is powered by a new server engine called Nitro. Nitro is used in development and production. It includes cross-platform support for Node.js, browser engines, service workers and serverless. It enables API routes, code-splitting, async-loaded chunks, and hybrid static/serverless modes. The Server API endpoints and middleware internally use h3.

Handlers can directly return objects/arrays for JSON response
Handlers can return promises that are awaited (res.end() and next() are also supported)
Helper functions include body parsing, cookie handling, redirects, and headers

Nitro allows 'direct' calling of routes via the globally-available $fetch helper. If run on the browser it will make an API call to the server. But it will call the relevant function if run on the server and save an additional API call. The $fetch API uses ohmyfetch to:

Automatically parse JSON responses (with access to raw responses if needed)
Automatically handle request body and params with correct Content-Type headers added

Server Directory for API Routes

The server directory contains API endpoints and server middleware for your project. It is used to create any backend logic for your Nuxt application. Nuxt will automatically read in any files in the ~/server/api directory to create API endpoints. Each file should export a default function that handles API requests.

mkdir -p server/api
echo > server/api/index.js

Add the following code to index.js.

// server/api/index.js

export default (req, res) => (`
  <h2>Hello from Nuxt 3</h2>
`)

Open localhost:3000/api and make sure not to include a trailing slash or it will error out.

We could also flesh out this route into a full HTML document.

// server/api/index.js

export default (req, res) => (`
  <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="description" content="A minimal HTML website served on a Nuxt API route.">
      <title>Nuxt 3 API Route</title>
    </head>

    <body>
      <header>
        <h2>Hello from Nuxt 3</h2>
      </header>
      <footer>ajcwebdev '22</footer>
    </body>
  </html>
`)

Deployment

What's the point of a framework if you can't deploy it on multiple Jamstack platforms?

Deploy to Vercel

yarn vercel

? Set up and deploy “~/ajcwebdev-nuxt3”? [Y/n] y
? Which scope do you want to deploy to? Anthony Campolo
? Link to existing project? [y/N] n
? What's your project's name? ajcwebdev-nuxt3
? In which directory is your code located? ./

Auto-detected Project Settings (Nuxt.js):
- Build Command: nuxt generate
- Output Directory: dist
- Development Command: nuxt
? Want to override the settings? [y/N] n

🔗  Linked to ajcwebdev/ajcwebdev-nuxt3 (created .vercel and added it to .gitignore)
🔍  Inspect: https://vercel.com/ajcwebdev/ajcwebdev-nuxt3/2hzPze5Wmzv9hDxNXGovirFLgw4X [5s]
✅  Production: https://ajcwebdev-nuxt3.vercel.app [copied to clipboard]
📝  Deployed to production. Run `vercel --prod` to overwrite later (https://vercel.link/2F).
💡  To change the domain or build command, go to https://vercel.com/ajcwebdev/ajcwebdev-nuxt3/settings

Open ajcwebdev-nuxt3.vercel.app.

Deploy to Netlify

echo > netlify.toml

[build]
  command = "yarn build"
  publish = "dist"
  functions = ".output/server"

[[redirects]]
  from = "/*"
  to = "/.netlify/functions/index"
  status = 200

Create a GitHub repository with the GitHub CLI by running the following series of commands or visit repo.new and follow the instructions provided there.

git init
git add .
git commit -m "the nuxt best thing"
gh repo create ajcwebdev-nuxt3 --public --push \
  --source=. \
  --description="An example Nuxt 3 application deployed on Netlify and Vercel" \
  --remote=upstream

Connect your repo to your Netlify account.

The build command and publish directory will be included automatically from the netlify.toml file.

Lastly, give yourself a custom domain.

Open ajcwebdev-nuxt3.netlify.app.

Why Am I Hung Up on the Term Fullstack?

ajcwebdev — Tue, 05 Oct 2021 20:19:37 +0000

Stacks evolve over time. But it’s not just what technologies they use, but what technology we even consider a part of a stack. What fullstack means morphs over time.

Chris Coyier - What Does it Mean to Be “Full Stack”?

Today I got into a Twitter #BEEF about the appropriateness of the term "fullstack framework." Some of you may know that I am the host of a podcast called Fullstack Jamstack and have made my name as a developer advocate for RedwoodJS, a self proclaimed "fullstack" JavaScript framework.

However, I do not make any claims to ownership of the term. My thoughts on the term and its definition are fiercely personal, and I welcome others to have their own passionate beliefs around it. I want to elicit dialogue around the term, not tell you what it means.

Why is this personal for me?

Before joining the RedwoodJS team I was learning how to code at Lambda School, learning a "fullstack web development" curriculum. This curriculum contained roughly:

10% HTML/CSS
85% JavaScript/React
5% Node/Express/Postgres

I felt this was an uneven split between the frontend and backend. It didn't seem accurate to label this as a "fullstack" curriculum, instead it seemed more accurate to call it a "frontend" curriculum with a very small amount of backend material included at the end.

What is the definition of "Full?"

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

I start with the postulate that the term "full" contains the most essential quality of "completeness." To say something is "full," is to say there is nothing left to add. This is why I would consider a stack without any database or storage to be incomplete.

How often do you use an application where everything you did with that application disappears after you take a break from using it? If you're just reading a blog post that's probably fine, not everything we do on the web requires persistence. But if you're writing that blog post, it's a different story.

Is there actually just a frontend and backend?

A recent turn of phrase has come up called the "front of the backend" to describe the illusive middle ground between the client side and the server side. Does this mean there is a "back of the frontend?"

There is the HTML and CSS for the content and styling and JavaScript (or some sort of JavaScript framework) for the client side interaction. But the data fetching logic and state management can be decoupled from the content and styling itself, forming its own layer of the application. This is the space Redux and React Query play in.

On the backend you have an operating system, server side language (or framework), and database for authentication, authorization, and persistence. But you can abstract a layer above that with an API mesh, serverless functions, or containers that let you ignore the actual operations of the underlying system.

What else should be included in the definition of "fullstack?"

What about accessibility, internationalization, localization, security, deployment, DevOps, automated testing, design systems, data collection, analytics, emails, etc? How wide does the definition go? Is it even reasonable for us to expect a single developer to ever be fullstack?

Unfortunately I don't have the answer to that question. But as long as we are going to be selling the term for our bootcamps, our frameworks, and our podcasts, then we need to think carefully about what we mean when we use the term.

Thank you to Alex for his thoughtful notes and pushback on this piece.

Three Ways to Deploy a Serverless GraphQL API

ajcwebdev — Mon, 04 Oct 2021 19:56:03 +0000

Outline

Introduction
Pros and Cons
Deployment Providers
- Netlify Functions
- Serverless Framework
- Amplify
Serve Apollo Server Locally
Deploy Apollo Server Lambda with Netlify
Deploy Apollo Server Lambda with Serverless Framework
Deploy Apollo Server Lambda with Amplify
Serve GraphQL Yoga Locally
Deploy GraphQL Yoga with Netlify
Deploy GraphQL Yoga with Serverless Framework
Deploy GraphQL Yoga with Amplify

All of this project's code can be found in the First Look monorepo on my GitHub.

Introduction

There are a wide range of different options for GraphQL servers with varying deployment methods. Typical methods for hosting your server include virtual machines (AWS EC2, Digital Ocean Droplet) or containers (Cloud Run, AWS ECS). However, if your server does not need to persist state, then you can host it using a serverless function. This includes:

Bundling your application into a zip file
Storing that static file somewhere with blob storage like an S3 bucket
Serving that file using an API gateway and serverless function like an AWS Lambda

Pros and Cons

The benefits include removing large amounts of operations work such as managing the operating system of underlying VMs or creating optimized Dockerfiles. You also no longer need to worry about scaling your application or paying for idle time when your server is not being used.

Since the server state cannot be persisted, the drawbacks include removing the ability to use websockets or subscriptions. The functions will only work for basic GET and POST methods. You also need to write your code with the syntax of the underlying runtime which requires keeping in mind information such as the available Node version and compatible dependencies.

Deployment Providers

This article looks at three different methods of deploying two different GraphQL servers: Apollo Server and GraphQL Yoga. They will be deployed with Netlify Functions, Serverless Framework, and AWS Amplify. All three use the same underlying technology, AWS Lambda functions. They differ in terms of the conventions and abstractions around creating, developing, and deploying those functions.

Netlify Functions

Netlify Functions are scripts that you can write and deploy directly on Netlify. Netlify lets you deploy serverless Lambda functions without an AWS account, and with function management handled directly within Netlify. It requires the least amount of knowledge of AWS, but also gives you the least amount of control over the underlying infrastructure.

Lambda functions can be added to a project by creating a JavaScript file in a configured functions directory. The function endpoint is determined by its filename or the name of its dedicated parent directory. It exports a handler that receives an event object similar to what you would receive from AWS API Gateway.

Serverless Framework

The Serverless Framework is an open source framework for building applications on AWS Lambda. It provides a CLI for developing and deploying AWS Lambda functions, along with the AWS infrastructure resources they require.

The resources and functions are defined in a file called serverless.yml which includes:

The provider for the Node runtime and AWS region
The handler and events for your functions

Once the project is defined in code it can be deployed with the sls deploy command. This command creates a CloudFormation stack defining any necessary resources such as API gateways or S3 buckets.

Amplify

AWS Amplify is a set of tools and services to help frontend web and mobile developers build fullstack applications with AWS infrastructure. It includes a CLI for creating and deploying CloudFormation stacks along with a Console and Admin UI for managing frontend web apps, backend environments, CI/CD, and user data.

Amplify provides open source libraries in various languages including:

The amplify init command creates a boilerplate project that is setup for generating CloudFormation templates. amplify add api configures a Lambda handler and API gateway to serve the function. amplify push uploads the stack templates to an S3 bucket and calls the CloudFormation API to create or update resources in the cloud.

Serve Apollo Server Locally

Apollo Server is an open-source, spec-compliant GraphQL server. Apollo Server Core implements the core logic of Apollo Server.

mkdir apollo-server
cd apollo-server
yarn init -y
yarn add apollo-server graphql
touch index.js
echo 'node_modules\n.DS_Store' > .gitignore

ApolloServer

apollo-server exports a base version of the ApolloServer constructor which requires two parameters, typeDefs for a schema definition and resolvers for a set of resolvers. The listen method is used to launch the server.

// index.js

const { ApolloServer, gql } = require('apollo-server')

const typeDefs = gql`type Query { hello: String }`
const resolvers = {
  Query: { hello: () => "Hello from Apollo on Localhost!" }
}

const server = new ApolloServer({ typeDefs, resolvers })

server.listen().then(
  ({ url }) => { console.log(`Server ready at ${url}`) }
)

ApolloServer is usually imported either from a batteries-included apollo-server package or from integration packages like apollo-server-lambda.

Run test queries on Apollo Server Locally

Start the server with node index.js.

node index.js

Open localhost:4000 and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url http://localhost:4000/ \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

Apollo Server Final Project Structure

├── .gitignore
├── index.js
└── package.json

Deploy Apollo Server Lambda with Netlify

In Apollo Server 3, apollo-server-lambda is implemented as a wrapper around apollo-server-express and uses serverless-express to parse AWS Lambda events into Express requests. This will cause problems with Netlify Functions, so instead we will install v2.

mkdir -p apollo-server-netlify/netlify/functions
cd apollo-server-netlify
yarn init -y
yarn add apollo-server-lambda@2 graphql
touch netlify/functions/index.js
echo 'node_modules\n.DS_Store\n.netlify' > .gitignore

ApolloServer

Each JavaScript file to be deployed as a synchronous serverless Lambda function must export a handler method. Netlify provides the event and context parameters when the serverless function is invoked.

// netlify/functions/index.js

const { ApolloServer, gql } = require('apollo-server-lambda')

const typeDefs = gql`type Query { hello: String }`
const resolvers = {
  Query: { hello: () => "Hello from Apollo on Netlify!" }
}

const server = new ApolloServer({ typeDefs, resolvers })

exports.handler = server.createHandler()

Run test queries on Apollo Server Lambda Netlify Locally

Start the development server with netlify dev.

netlify dev

Open localhost:8888/.netlify/functions/index and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url http://localhost:8888/.netlify/functions/index \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

Create GitHub Repo and Connect to Netlify

git init
git add .
git commit -m "apollo server lambda netlify"
gh repo create ajcwebdev-apollo-server-netlify
git push -u origin main
netlify deploy --prod

Run test queries on Apollo Server Lambda Netlify

Open ajcwebdev-apollo-server-netlify.netlify.app/.netlify/functions/index and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url https://ajcwebdev-apollo-server-netlify.netlify.app/.netlify/functions/index \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

Apollo Server Lambda Netlify Final Project Structure

├── .gitignore
├── netlify
│   └── functions
│       └── index.js
└── package.json

Deploy Apollo Server Lambda with Serverless Framework

mkdir apollo-server-serverless
cd apollo-server-serverless
yarn init -y
yarn add apollo-server-lambda graphql
touch index.js serverless.yml
echo 'node_modules\n.DS_Store\n.serverless' > .gitignore

ApolloServer

// index.js

const { ApolloServer, gql } = require('apollo-server-lambda')

const typeDefs = gql`type Query { hello: String }`
const resolvers = {
  Query: { hello: () => 'Hello from Apollo on Serverless Framework!' }
}

const server = new ApolloServer({ typeDefs, resolvers })

exports.handler = server.createHandler()

Serverless Framework Configuration

The handler is formatted as <FILENAME>.<HANDLER>. I have included us-west-1 for the region, feel free to enter the AWS region closest to your current location.

# serverless.yml

service: ajcwebdev-apollo-server
provider:
  name: aws
  runtime: nodejs14.x
  region: us-west-1
functions:
  graphql:
    handler: index.handler
    events:
    - http:
        path: /
        method: post
        cors: true
    - http:
        path: /
        method: get
        cors: true

Upload to AWS with sls deploy

sls deploy

service: ajcwebdev-apollo-server
stage: dev
region: us-west-1
stack: ajcwebdev-apollo-server-dev
resources: 12
api keys:
  None
endpoints:
  POST - https://q6b9hu1h71.execute-api.us-west-1.amazonaws.com/dev/
  GET - https://q6b9hu1h71.execute-api.us-west-1.amazonaws.com/dev/
functions:
  graphql: ajcwebdev-apollo-server-dev-graphql
layers:
  None

You can see all of your AWS resources in the various AWS consoles.

CloudFormation

Lambda Function

Lambda Application

API Gateway

Run test queries on Apollo Server Lambda Serverless

Open q6b9hu1h71.execute-api.us-west-1.amazonaws.com/dev/ and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url https://q6b9hu1h71.execute-api.us-west-1.amazonaws.com/dev/ \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

Apollo Server Lambda Serverless Final Project Structure

├── .gitignore
├── index.js
├── package.json
└── serverless.yml

Deploy Apollo Server Lambda with Amplify

mkdir apollo-server-amplify
cd apollo-server-amplify
amplify init

? Enter a name for the project ajcwebdevapollo
The following configuration will be applied:

Project information
| Name: ajcwebdevapollo
| Environment: dev
| Default editor: Visual Studio Code
| App type: javascript
| Javascript framework: none
| Source Directory Path: src
| Distribution Directory Path: dist
| Build Command: npm run-script build
| Start Command: npm run-script start

? Initialize the project with the above configuration? Yes
Using default provider  awscloudformation
? Select the authentication method you want to use: AWS profile

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

? Please choose the profile you want to use default

CloudFormation

Create backend with amplify add api

amplify add api

? Please select from one of the below mentioned services: REST
? Provide a friendly name for your resource to be used as a label for this category in the project: ajcwebdevapollo
? Provide a path (e.g., /book/{isbn}): /graphql
? Choose a Lambda source Create a new Lambda function
? Provide an AWS Lambda function name: apolloserver
? Choose the runtime that you want to use: NodeJS
? Choose the function template that you want to use: Hello World
? Do you want to access other resources created in this project from your Lambda function? N
? Do you want to edit the local lambda function now? N
? Restrict API access: N
? Do you want to add another path? N

cd amplify/backend/function/apolloserver/src
yarn add apollo-server-lambda graphql
cd ../../../../../

ApolloServer

// amplify/backend/function/apollofunction/src/index.js

const { ApolloServer, gql } = require('apollo-server-lambda')

const typeDefs = gql`type Query { hello: String }`
const resolvers = {
  Query: { hello: () => 'Hello from Apollo on Amplify!' }
}

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ event, context }) => ({
    headers: event.headers,
    functionName: context.functionName,
    event,
    context,
  }),
})

exports.handler = server.createHandler()

Upload to AWS with amplify push

Deploy the function containing the GraphQL API.

amplify push

✔ Successfully pulled backend environment dev from the cloud.

    Current Environment: dev

┌──────────┬─────────────────┬───────────┬───────────────────┐
│ Category │ Resource name   │ Operation │ Provider plugin   │
├──────────┼─────────────────┼───────────┼───────────────────┤
│ Function │ apolloserver    │ Create    │ awscloudformation │
├──────────┼─────────────────┼───────────┼───────────────────┤
│ Api      │ ajcwebdevapollo │ Create    │ awscloudformation │
└──────────┴─────────────────┴───────────┴───────────────────┘
? Are you sure you want to continue? Yes

All resources are updated in the cloud

REST API endpoint: https://kl21tioy61.execute-api.us-east-1.amazonaws.com/dev

Lambda Function

Lambda Application

API Gateway

Run test queries on Apollo Server Lambda Amplify

Open kl21tioy61.execute-api.us-east-1.amazonaws.com/dev/graphql and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url https://kl21tioy61.execute-api.us-east-1.amazonaws.com/dev/graphql \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

Apollo Server Lambda Amplify Final Project Structure

├── .gitignore
└── amplify
    └── backend
        ├── api
        │   └── ajcwebdevapollo
        │       ├── ajcwebdevapollo-cloudformation-template.json
        │       ├── api-params.json
        │       └── parameters.json
        └── function
            └── apolloserver
                ├── apolloserver-cloudformation-template.json
                ├── function-parameters.json
                └── src
                    ├── event.json
                    ├── index.js
                    └── package.json

Serve GraphQL Yoga Locally

GraphQL Yoga is a fully-featured GraphQL Server with a focus on easy setup and performance. Originally created by Prisma, it is now mained by Dotan and the Guild. It includes features aimed at providing a great developer experience including file uploading, GraphQL subscriptions support with WebSockets, and TypeScript typing.

graphql-yoga is built on other packages that provide functionality required for building a GraphQL server such as web server frameworks like express and apollo-server, GraphQL subscriptions with graphql-subscriptions and subscriptions-transport-ws, GraphQL engine & schema helpers including graphql.js and graphql-tools, and an interactive GraphQL IDE with graphql-playground.

mkdir graphql-yoga
cd graphql-yoga
yarn init -y
yarn add graphql-yoga
touch index.js
echo 'node_modules\n.DS_Store' > .gitignore

GraphQLServer

GraphQLServer is a constructor with a props argument that accepts a wide array of fields. We will only be using a handful including:

typeDefs - Contains GraphQL type definitions in SDL or file path to type definitions
resolvers- Contains resolvers for the fields specified in typeDefs
schema - An instance of GraphQLSchema

// index.js

const { GraphQLServer } = require('graphql-yoga')

const typeDefs = `type Query { hello: String }`
const resolvers = {
  Query: { hello: () => 'Hello from GraphQL Yoga on Localhost!' }
}

const server = new GraphQLServer({ typeDefs, resolvers })

server.start(
  () => console.log('Server is running on localhost:4000')
)

If you provide typeDefs and resolvers but omit the schema, graphql-yoga will construct the GraphQLSchema instance using makeExecutableSchema from graphql-tools.

Run test queries on GraphQL Yoga Locally

node index.js

Open http://localhost:4000 and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url http://localhost:4000/ \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

GraphQL Yoga Final Project Structure

├── .gitignore
├── index.js
└── package.json

Deploy GraphQL Yoga with Netlify

mkdir -p graphql-yoga-netlify/netlify/functions
cd graphql-yoga-netlify
yarn init -y
yarn add graphql-yoga
touch netlify/functions/index.js
echo 'node_modules\n.DS_Store\n.netlify' > .gitignore

GraphQLServerLambda

// netlify/functions/index.js

const { GraphQLServerLambda } = require('graphql-yoga')

const typeDefs = `type Query { hello: String }`
const resolvers = {
  Query: { hello: () => 'Hello from GraphQL Yoga on Netlify!' }
}

const lambda = new GraphQLServerLambda({ typeDefs, resolvers })

exports.handler = lambda.handler

Run test queries on GraphQL Yoga Netlify Locally

Start the development server with netlify dev.

netlify dev

Open localhost:8888/.netlify/functions/index and run the hello query.

curl --request POST \
  --url http://localhost:8888/.netlify/functions/index \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

Create GitHub Repo and Connect GraphQL Yoga to Netlify

git init
git add .
git commit -m "graphql yoga netlify"
gh repo create ajcwebdev-graphql-yoga-netlify
git push -u origin main
netlify deploy --prod

Run test queries on GraphQL Yoga Netlify

Open ajcwebdev-graphql-yoga-netlify.netlify.app/.netlify/functions/index and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url https://ajcwebdev-graphql-yoga-netlify.netlify.app/.netlify/functions/index \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

GraphQL Yoga Netlify Final Project Structure

├── .gitignore
├── netlify
│   └── functions
│       └── index.js
└── package.json

Deploy GraphQL Yoga with Serverless Framework

mkdir graphql-yoga-serverless
cd graphql-yoga-serverless
yarn init -y
yarn add graphql-yoga
touch index.js serverless.yml
echo 'node_modules\n.DS_Store\n.serverless' > .gitignore

GraphQLServerLambda

// index.js

const { GraphQLServerLambda } = require('graphql-yoga')

const typeDefs = `type Query { hello: String }`
const resolvers = {
  Query: { hello: () => 'Hello from GraphQL Yoga on Serverless Framework!' }
}

const lambda = new GraphQLServerLambda({ typeDefs, resolvers })

exports.handler = lambda.graphqlHandler
exports.playground = lambda.playgroundHandler

Serverless Framework Configuration

# serverless.yml

service: yoga-example 
provider:
  name: aws
  runtime: nodejs14.x
  region: us-west-1
functions:
  graphql:
    handler: index.handler
    events:
    - http:
        path: /
        method: post
        cors: true
  playground:
    handler: index.playground
    events:
    - http:
        path: /
        method: get
        cors: true

Upload to AWS with sls deploy

sls deploy

service: yoga-example
stage: dev
region: us-west-1
stack: yoga-example-dev
resources: 16
api keys:
  None
endpoints:
  POST - https://vptcz65b06.execute-api.us-west-1.amazonaws.com/dev/
  GET - https://vptcz65b06.execute-api.us-west-1.amazonaws.com/dev/
functions:
  graphql: yoga-example-dev-graphql
  playground: yoga-example-dev-playground
layers:
  None

Run test queries on GraphQL Yoga Serverless

Open vptcz65b06.execute-api.us-west-1.amazonaws.com/dev/ and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url https://vptcz65b06.execute-api.us-west-1.amazonaws.com/dev/ \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

GraphQL Yoga Serverless Final Project Structure

├── .gitignore
├── index.js
├── package.json
└── serverless.yml

Deploy GraphQL Yoga with Amplify

mkdir graphql-yoga-amplify
cd graphql-yoga-amplify
amplify init

? Enter a name for the project ajcwebdevgraphqlyoga
The following configuration will be applied:

Project information
| Name: ajcwebdevgraphqlyoga
| Environment: dev
| Default editor: Visual Studio Code
| App type: javascript
| Javascript framework: none
| Source Directory Path: src
| Distribution Directory Path: dist
| Build Command: npm run-script build
| Start Command: npm run-script start

? Initialize the project with the above configuration? Yes
Using default provider  awscloudformation
? Select the authentication method you want to use: AWS profile

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

? Please choose the profile you want to use default

Create backend with amplify add api

amplify add api

? Please select from one of the below mentioned services: REST
? Provide a friendly name for your resource to be used as a label for this category in the project: ajcwebdevyoga
? Provide a path (e.g., /book/{isbn}): /graphql
? Choose a Lambda source: Create a new Lambda function
? Provide the AWS Lambda function name: graphqlyoga
? Choose the function runtime that you want to use: NodeJS
? Choose the function template that you want to use: Hello World
? Do you want to access other resources created in this project from your Lambda function? N
? Do you want to edit the local lambda function now? N
? Restrict API access: N
? Do you want to add another path? N

cd amplify/backend/function/graphqlyoga/src
yarn add graphql-yoga
cd ../../../../../

GraphQLServerLambda

// amplify/backend/function/graphqlyoga/src/index.js

const { GraphQLServerLambda } = require('graphql-yoga')

const typeDefs = `type Query { hello: String }`
const resolvers = {
  Query: { hello: () => 'Hello from GraphQL Yoga on Amplify!' }
}

const lambda = new GraphQLServerLambda({ typeDefs, resolvers })

exports.handler = lambda.handler

Upload to AWS with amplify push

Deploy the function containing the GraphQL API.

amplify push

✔ Successfully pulled backend environment dev from the cloud.

    Current Environment: dev

┌──────────┬───────────────┬───────────┬───────────────────┐
│ Category │ Resource name │ Operation │ Provider plugin   │
├──────────┼───────────────┼───────────┼───────────────────┤
│ Function │ graphqlyoga   │ Create    │ awscloudformation │
├──────────┼───────────────┼───────────┼───────────────────┤
│ Api      │ ajcwebdevyoga │ Create    │ awscloudformation │
└──────────┴───────────────┴───────────┴───────────────────┘
? Are you sure you want to continue? Yes

All resources are updated in the cloud

REST API endpoint: https://zmvy0jw9dc.execute-api.us-east-1.amazonaws.com/dev

CloudFormation

Lambda Function

Lambda Application

API Gateway

Run test queries on GraphQL Yoga Amplify

Open zmvy0jw9dc.execute-api.us-east-1.amazonaws.com/dev/graphql and run the hello query.

query HELLO_QUERY { hello }

curl --request POST \
  --url https://zmvy0jw9dc.execute-api.us-east-1.amazonaws.com/dev/graphql \
  --header 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

GraphQL Yoga Amplify Final Project Structure

├── .gitignore
└── amplify
    └── backend
        ├── api
        │   └── ajcwebdevyoga
        │       ├── ajcwebdevyoga-cloudformation-template.json
        │       ├── api-params.json
        │       └── parameters.json
        └── function
            └── graphqlyoga
                ├── amplify.state
                ├── graphqlyoga-cloudformation-template.json
                ├── function-parameters.json
                └── src
                    ├── event.json
                    ├── index.js
                    └── package.json

You're still here? Wow, didn't think anyone would actually make it to the end.

The Potential of web3

ajcwebdev — Fri, 01 Oct 2021 22:14:49 +0000

After the recent influx of questions and attention around Web3, I've decided to republish a blogpost I originally wrote about the topic on February 8, 2018.

The Year Crypto Went Mainstream

2017 was finally the year crypto went mainstream. I’ve seen a lot of musicians transition from semi-indie famous to full blown celebrities, and when I’m trying to gauge how much exposure a musician truly has, my litmus test has always been, “Do my parents know who this is, and do teenagers know who this is?” 2017 is the year that crypto passed that litmus test.

Hype vs. Reality

Unfortunately the conversation has mostly centered around the speculative price volatility due to trading, rather than the underlying technology. This is a massive red herring. While it’s true that cryptoassets will continue to develop and generate extreme amounts of wealth in the coming years, the true potential for the blockchain is 3-fold:

Create a sustainable structure for an open source project to be funded and nurtured throughout its development.
Secure your data from the bottom up by cryptographically hashing every transaction.
Allow for radical transparency in observing the amount of money moving throughout a system. The transactions may not have identifiable names on them, but every transaction is equally observable to every user of the system. We may never know who Satoshi is but everyone can see his coins.

It’s almost too good to be true. At the moment when our tech institutions have failed us miserably there is a grassroots movement metastasizing out of the ground to solve all of the internet’s ills. It’s like a thousand Linux projects appeared overnight. But this is only one possible future for blockchains and cryptocurrencies. We collectively decide the future through our focus and attention.