DEV Community: Brittney Postma

Migrating Breaking Changes in SvelteKit

Brittney Postma — Mon, 29 Aug 2022 18:16:38 +0000

SvelteKit has gone through a few breaking changes recently including an entire routing overhaul, changes to the load API, and a switch to the Vite CLI. If you’ve used it in the past, it may look quite a bit different than it used to. Just looking at the August updates, there were ten breaking changes. It’s a lot to keep up with, so this post will review the biggest breaking changes and navigate you through migrating an app to get it up to date.

So Long File Based Routing

By far the biggest change in SvelteKit is doing away with file-based routing. There is still a routes directory where you will create your routes, but they are now directory based and require a + prefix to generate a route.

Routing The Old Way

Before, any file added to the routes directory would create a route at that name. This made it difficult to colocate files without more confusing syntax. Double underscores, __ indicated a layout or error route, and a single underscore, _ would skip creating it as a route. Things were messy and nothing was grouped together.

📂 src
└ 📂 routes
  ├ 📄 index.svelte
  ├ 📄 about.svelte
  ├ 📄 __layout.svelte
  ├ 📄 __layout-nested.svelte
  ├ 📄 __error.svelte
  └ 📂 nested-route
    └ 📄 _component-for-nested.svelte  
    └ 📄 index@nested.svelte

Routing The New Way

Now all routes are directory based, other than the home or root route, all new routes need to be in a folder. The old index.svelte has gone away in favor of +page.svelte to indicate you are deliberately creating a route. You also no longer need the underscore, _, to colocate a component to a route. It’s much clearer what route each file is attached to in the new routing structure.

📂 src
└ 📂 routes
  ├ 📄 +page.svelte
  ├ 📄 +layout.svelte
  ├ 📄 +error.svelte
  └  📂 about
     ├ 📄 coc.svelte
     ├ 📄 +page.svelte
     └ 📄 +layout.svelte

Resources

To find out more about why these changes happened, there are some really good conversations that happened on GitHub and the documentation walks through the new setup.

Layout Overhaul

Layouts in Svelte have gone through a major overhaul. No longer do multiple layouts live in the root of the routes directory, then naming them on a file such as index@nested.svelte. Basic layouts are now +layout.svelte files and will inherit from the root layout no matter how nested they are.

Layouts The Old Way

📂 src
└ 📂 routes
  ├ 📄 index.svelte
  ├ 📄 __layout.svelte
  ├ 📄 __layout-nested.svelte
  └ 📂 nested-route
    └ 📄 index@nested.svelte

Layouts The New Way

📂 src
└ 📂 routes
  ├ 📄 +page.svelte
  ├ 📄 +layout.svelte
  └  📂 about
     ├ 📄 +page.svelte
     └ 📄 +layout.svelte // will inherit the src/routes/+layout.svelte layout

Group Layouts

There is also a new convention to share layouts with a folder wrapped in parenthesis()called a group directory. Group directories do not affect the URL pathname of the nested routes, it essentially acts as a root route. A +page.svelte file can be added to a (group) directory root if the / or home route should be the group. Since layouts inherit all the way down, you may want to use a different layout in a nested route. To do that we can still use the named layout syntax of +page@nested.svelte where nested is the name of the layout you wish to use. To opt out of a layout entirely and reset it, create a +layout@.svelte file in the directory by the +page.svelte file that needs reset.

📂 src
└ 📂 routes
  ├ 📄 +layout.svelte
  └  📂 (marketing) // group routes
     ├ 📂 about
       ├ 📂 embed
         ├ 📄 +page.svelte
         └ 📄 +layout@(marketing).svelte // this will skip the about layout
       └ 📄 +layout.svelte
     ├ 📂 coc
       ├ 📄 +page.svelte
       └ 📄 +layout@.svelte //this will opt out of all layouts
     ├ 📄 +page.svelte // lives at / not /marketing
     └ 📄 +layout.svelte

Resources

These changes were not the most straightforward and even the documentation is a little difficult to parse right now, but it is there. I found the discussion of the changes on GitHub to be more helpful and easier to understand.

Removing Confusion on Load

The load function is how a SvelteKit route receives outside data, such as from a database or 3rd party API. Before there was always confusion around whether the load function ran on the server or the client and was never clear if secrets were leaking through to the client. The load function has now moved out of the .svelte file and into an endpoint file.

Load The Old Way

Before, the load function lived in the context="module" script tag inside of the .svelte file or the data for the route was magically returned from an endpoint. Not all that long ago, another change occurred to the way data was loaded into a component. While the official name was page endpoints, us diehards kept fighting for the obviously cooler sounding shadow endpoints. These automagically loaded the data from the endpoint directly into the .svelte route by returning the data and then exporting a prop of the same name in the route.

📂 src
└ 📂 routes
  ├ 📄 index.svelte
  ├ 📄 index.js
  ├ 📄 about.svelte
  ├ 📄 about.js
  ├ 📄 __layout.svelte
  ├ 📄 __layout-nested.svelte
  ├ 📄 __error.svelte
  └ 📂 nested-route
    ├ 📄 index.js
    └ 📄 index@nested.svelte

// in a .svelte route
<script context="module">
  export const load = () => {
    let propName = "arbitrary data"
    return {
      props: {
    propName
      }
    }
  }
</script>

<script>
  export let propName
</script>

<h1>Use the {propName}</h1>

Load The New Way

Now the load function has moved into the endpoint file and the magical loading of data into the .svelte file still exists and passes to the route with the data prop. There are two new files you can use to load data into a route. The +page.js (or +page.ts for TypeScript) runs on the server during server-side rendering and again in the client when client-side navigating. There is also a +page.server.js that will only run on the server making it safe for API keys and secure SDKs you don’t want leaked to the client. You also no longer need to return the data inside of a props object. You determine where that data loads, either only on the server or both the server and client. In the +page.svelte route file, the prop is simply named data now.

📂 src
└ 📂 routes
  ├ 📄 +page.svelte
  ├ 📄 +page.js
  ├ 📄 +layout.svelte
  ├ 📄 +error.svelte
  └  📂 about
     ├ 📄 +page.svelte
     ├ 📄 +page.server.js
     └ 📄 +layout.svelte

// in a +page.js or +page.server.js endpoint
// copy over your load function from before
export const load = () => {
  let propName = "arbitrary data"
  return {
    // remove the props object 
    propName
  }
}

// in a +page.svelte route
<script>
  export let data
</script>

<h1>Use the {data.propName}</h1>

Page Behavior

The exports that dictated a pages behavior have also moved from the <script context="module"> into the endpoint file +page.js.

export const prerender = true or false overrides config.kit.prerender.default
export const hydrate = true or false overrides config.kit.browser.hydrate
export const router = true or false overrides config.kit.browser.router

Resources

Here are some links to the documentation for the new endpoint files and loading data.

All in on Vite

SvelteKit has gone all in on the Vite ecosystem by pulling out the Vite config and becoming a Vite plugin. Way back in the day SvelteKit ran on Snowpack. They made the decision to switch after Vite version 2 came out in 2021 and added support for other frameworks besides Vue. That was just the underlying build tool and SvelteKit was still passing along the Vite configuration through its own svelte.config.js file and using its own sveltekit CLI command for running the dev and build scripts. This was using an experimental method and the goal was to move to a more standard way that frameworks typically interact with Vite, through a plugin. This allows for first-party support for tools like Vitest and Storybook that look for a Vite config file. With the new changes, SvelteKit is just a Vite project that uses the @sveltejs/kit/vite plugin and switched to the Vite CLI for the dev and build scripts. There is now a vite.config.js file at the root of a SvelteKit project, that includes the plugin along with any other Vite configuration.

Vite The Old Way

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import preprocess from 'svelte-preprocess';

/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://github.com/sveltejs/svelte-preprocess
// for more information about preprocessors
preprocess: preprocess(),

  kit: {
    adapter: adapter(),
    vite: {
      // vite config stuff
    }
  };

export default config;

// package.json
{
  "scripts": {
    "dev": "svelte-kit dev",
    "build": "svelte-kit build",
    "preview": "svelte-kit preview",
  }
}

Vite The New Way

// vite.config.js
import { sveltekit } from '@sveltejs/kit/experimental/vite';

export default {
  plugins: [ sveltekit() ]
};

// package.json
{
  "scripts": {
      "dev": "vite dev",
      "build": "vite build",
      "preview": "vite preview",
  }
}

Migrating Changes

With big change always comes a lot of frustration for users. The maintainers of SvelteKit took this in mind and created an entire migration guide and a command, npx svelte-migrate routes, that attempts to make a lot of the changes for you. The script will rename the files inside the routes directory, comments out anything in a context module script tag, and throws errors to tell you to update to the data prop. However, no tool can take care of everything and there will still be manual changes that need to updated. Depending on how long it’s been since you’ve upgraded, you may have several things to change. Here are the overview steps to follow.

Remove old lock files and node_modules.

rm -rf node_modules package-lock.json # or yarn-lock or pnpm-lock

Update dependencies through your package manager.
```
npm i # or yarn or pnpm
```
Run the migration command. The routes will be renamed and placed in the new directory structure and endpoint files will attempt to move to the appropriate type.
```
npx svelte-migrate routes
```

Update any props in +page.svelte files to data.

- export let propName
+ export let data

Remove any <script context="module"> stuff over to an endpoint file.

// in a +page.js or +page.server.js endpoint
// copy over your load function from the .svelte file
export const load = () => {
    let propName = "arbitrary data"
    return {
      // remove the props object 
      propName
    }
}

Make sure your scripts have been updated to the Vite CLI in the package.json.

// package.json
{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "preview": "vite preview",
  }
}

Try to run it!
```
npm run dev # or yarn or pnpm
```

These steps are just a general overview of the biggest changes. Depending on when you last upgraded, there may be other steps to follow. SvelteKit errors are pretty good and may help walk you through any other changes you need to make. There may also be unique situations in your app that will need more work. With the addition of the +page.server.js file, ensure you are loading your data where you need it. This will hopefully get you most of the way there.

Resources

To find out more information about the migration, check out the migration guide and you can always view the most recent updates in the SvelteKit Docs.

Moving Forward

With so many changes lately in SvelteKit, a lot of us are hoping to see the light at the end of the tunnel soon. Let’s hope these rapid changes mean we are getting close to 1.0. Hopefully this post helped bridge the gap to the latest changes. Go forth and migrate!

Other Resources

Here are a few extra resources to continue getting up to date with everything in SvelteKit.

A few podcasts have been talking about the recent changes. If you prefer listening to reading check out these Svelte Radio and SyntaxFM episodes.

Svelte Radio - SvelteKit is changing Fast
Svelte Radio - Let’s talk about Routing with Rich Harris
SyntaxFM - Supper Club x Rich Harris, Author of Svelte

Easy HTML Forms in SvelteKit with Netlify Forms

Brittney Postma — Wed, 10 Aug 2022 11:43:21 +0000

Forms are a necessary evil in web development. We may not want to deal with them, but sometimes we have to. Netlify makes this easy with built-in form handling. This is done at build time by parsing static html files, with no extra API calls or server-side logic needed. These are standard HTML forms with a data attribute for Netlify’s bots to detect it. We can utilize this great feature in new meta-frameworks like SvelteKit too by creating a prerendered route and using the HTML form. Let’s go through the steps to get your own Netlify form setup on SvelteKit.

| Updated for latest SvelteKit changes as of 8/22/22

Setting up SvelteKit

To start up a new SvelteKit project, run npm init svelte@next your-site-name in a terminal where you want the directory to live. It’s important to mention that at the time of writing, SvelteKit is still in beta, meaning some things will probably change. The @next will be dropped when it hits an official 1.0. This command will prompt a command line interface, CLI, asking what things you want setup in your project. Step through the CLI, setting up your project with the Skeleton application. Once you hit enter on the last prompt, your new SvelteKit app is created and it prints a list of next steps.

cd your-site-name
npm install (or pnpm, or yarn, etc)
git init && git add -A && git commit -m "Initial commit" (optional)
npm run dev -- --open (or your package manager of choice)
To close the dev server, hit Ctrl+C

Netlify Adapter

SvelteKit uses the concept of adapters to adapt the application to the platform you are deploying to. For Netlify, we can use the adapter-static or adapter-netlify. The static adapter will prerender your entire site. The Netlify adapter gives you more flexibility by allowing you to decide how to render each route, including putting them on the *edge.* For this demo, we’ll be using the adapter-netlify.

Install the adapter.
```
npm i -D @sveltejs/adapter-netlify
```

Open up the svelte.config.js file and edit the adapter import.

- import adapter from '@sveltejs/adapter-auto'
+ import adapter from '@sveltejs/adapter-netlify'

Netlify TOML files

Netlify uses a netlify.toml file to hold information about build, dev, and function configuration and setup. Create a netlify.toml file at the root of your SvelteKit site. Inside add the following build configurations.

[build]
    command = "npm run build"
    publish = "build/"
    functions = "functions/"

In SvelteKit, the routes directory is where the pages of your site live. A route file is created by adding a folder and prefixing the file with a +. The types of route files can be a +page.svelte and either a +page.server.js or a +page.js endpoint. The +page.svelte file is for the markup and the other files load the data into it and tell the page how to behave. The +page.server.js will only run on the server while the +page.js will run on the server and hydrate on the client. If you chose the skeleton project from the CLI, you will only have a +page.svelte file inside the routes directory as the / route. We'll create a +page.js file beside it to prerender the home route.

export const prerender = true

Now over in the +page.svelte file we can add the markup for the Netlify form.

<form name="netlify-form-example" method="POST" netlify-honeypot="bot-field" data-netlify="true">
  <input type="hidden" name="form-name" value="netlify-form-example" />
  <label for="name">Name</label>
  <input name="name" id="name" required placeholder="Name" type="text" />
  <label for="email">Email</label>
  <input name="email" id="email" required placeholder="Email" type="email" />
  <label for="message">Message</label>
  <input name="message" id="message" required placeholder="Message" type="text" />
  <input type="submit" value="Submit" />
</form>

There is a lot to take in here, so let’s look at it line by line.

The form element has several attributes on it, name, method, netlify-honeypot, and data-netlify.
```
<form name="netlify-form-example" method="POST" netlify-honeypot="bot-field" data-netlify="true">
```
1. The name can be whatever you want to call your form and will be what you see in your Netlify dashboard once the form is deployed.
2. The method must be "POST" to allow it to post to Netlify’s servers.
3. The netlify-honeypot attribute is optional, but will attempt to catch bots and filter them out.
4. The data-netlify="true" is the secret sauce. This is what Netlify’s bots will look for when crawling the static output of your site.
The hidden input element is the other piece of magic for Netlify to detect the form correctly
```
<input type="hidden" name="form-name" value="netlify-form-example" />
```
1. The type="hidden" attribute ensures it isn’t seen by visual users or screen readers.
2. The name="form-name" must be kept as is. Do NOT change the name to your actual form name.
3. The value attribute is where you match the name of your form up to the input. Whatever value you set the form name attribute to is what should be set to value in the hidden input field.
All the other inputs in the form are any valid HTML inputs that you would use in a regular form to get data from your user.

Deploy to Netlify

Now that the form is setup and is ready to be deployed to Netlify, we can finish the steps to deploy the site. If you are not already a Netlify user, go ahead and sign up for free.

Git Setup

If you didn’t setup the git init in the SvelteKit setup, now is the time to put your site on your favorite git provider.

git init && git add -A && git commit -m "Initial commit"

Create a repository, either using the CLI or by going directly to github.com. Link the new repository to your local site by copying the URL.

Run the command to add the remote origin pasting your URL at the end.

git remote add origin https://github.com/brittneypostma/sveltekit-netlify-forms

Push your code to GitHub using the current branch, which is typically main.
```
git push origin main
```

Link to Netlify

Now that the site is on a git provider, head to your Netlify dashboard.

Click on the Add new site button that drops down and click on Import an existing project.

Choose your Git provider.

Use the search box to find your repo.

Since we set up a netlify.toml earlier, the build settings should populate automatically. So just click the Deploy site button and Netlify’s robots will start building your site.

Checking the form

Once the site is deployed, head to your site URL. Fill in the form and click the Submit button.

When the form is submitted successfully, you will be redirected to a Netlify page that says your form submission has been received.

Back in your Netlify dashboard, click on the Forms tab,

Down below the forms section will be a list of active forms with the names you set in your HTML.

Click into the form to see your submission.

And that is it, no backend logic or complicated API calls, just straightforward form management with a pure HTML form. Happy form making!

How to Use Tailwind CSS with Remix

Brittney Postma — Tue, 09 Aug 2022 22:57:52 +0000

Tailwind CSS has become a very popular option for styling applications. It uses atomic utility classes that are preconfigured with good defaults to get started easily. Remix is a JavaScript framework that aims to make creating a production ready application easier than ever. It uses React for the UI layer. Using Remix and Tailwind CSS together is a really powerful option to get your applications built quickly. To get started with Tailwind CSS in a fresh Remix application, we’ll run the following commands to create the Remix app or skip directly to the Tailwind setup.

Setting up Remix

Run the command to start the CLI.
```
npx create-remix@latest
```
Name your project and select “Just the basics”.

Select Netlify from the list of deployment targets.

Use either TypeScript or JavaScript, it’s your choice.

Run npm install by hitting Y.

Now your Remix project is set up. You can open it in your favorite code editor and start setting up Tailwind CSS.

Setting up Tailwind CSS

Install the required packages for Tailwind.

npm install -D tailwindcss postcss autoprefixer concurrently

Run the command to initialize Tailwind, this will generate a tailwind.config.js file in the root of your project.
```
npx tailwindcss init
```

Open the newly created tailwind.config.js file and add the file paths to the content section.

// tailwind.config.js
/** @type {import('tailwindcss').Config} */ 
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Replace the scripts in the package.json with the new Tailwind scripts. These add two scripts to generate the Tailwind CSS files and updates the build and dev scripts to use the new CSS scripts. The path to the CSS files can be configured as needed, but by default it puts the initial file in the root styles/app.css file and the generated output goes to app/styles/app.css.
```
// package.json
{
  "scripts": {
    "build": "npm run build:css && remix build",
    "build:css": "tailwindcss -m -i ./styles/app.css -o app/styles/app.css",
    "dev": "concurrently \"npm run dev:css\" \"remix dev\"",
    "dev:css": "tailwindcss -w -i ./styles/app.css -o app/styles/app.css"
  }
}
```
Where you set the path of your CSS to or the default location styles/app.css, create the initial location for the CSS. From the root of your project, run the following commands.
```
mkdir styles
touch styles/app.css
```

Add the @tailwind directives to the newly created app.css file.

@tailwind base;
@tailwind components;
@tailwind utilities;

Run npm run dev to generate the output CSS file in app/styles/app.css.

Import the generated CSS file into the app/root.tsx file.

import styles from "./styles/app.css"

export function links() {
  return [{ rel: "stylesheet", href: styles }]
}

One thing I ran into that I wanted to note here. Make sure your Remix app includes the <Links /> component from @remix-run/react inside your app/root.tsx file or the links will not be added.

import { Links } from "@remix-run/react";
import styles from "./styles/app.css"
{/* ... */}
export function links() {
  return [{ rel: "stylesheet", href: styles }]
}
{/* ... */}
export default function Root() {
  return (
    <html>
      <head>
        <Links />
        {/* ... */}
      </head>
      {/* ... */}
    </html>
  );
}

Now you are setup to start using Tailwind classes inside of your components. Try it in the app/routes/index.tsx file. Remove the inline style from the wrapper div element and add in the Tailwind classes, className="font-sans leading-5 m-4". And give the h1 some styles, className="text-3xl font-bold text-teal-600". Make sure your dev server is running, npm run dev, and open localhost://3000 to see your Tailwind styles applied.

export default function Index() {
  return (
    <div className="font-sans leading-5 m-4">
      <h1 className="text-3xl font-bold text-teal-600">Welcome to Remix</h1>
      <ul>
        <li>
          <a
            target="_blank"
            href="https://remix.run/tutorials/blog"
            rel="noreferrer"
          >
            15m Quickstart Blog Tutorial
          </a>
        </li>
        <li>
          <a
            target="_blank"
            href="https://remix.run/tutorials/jokes"
            rel="noreferrer"
          >
            Deep Dive Jokes App Tutorial
          </a>
        </li>
        <li>
          <a target="_blank" href="https://remix.run/docs" rel="noreferrer">
            Remix Docs
          </a>
        </li>
      </ul>
    </div>
  );
}

K-Pop Stack

Another option with Tailwind CSS already preconfigured is the K-Pop Stack. Netlify's templates team has created this stack that is already configured with Tailwind and it uses Supabase for the database.

Intro to Serverless Functions

Brittney Postma — Mon, 25 Jul 2022 12:30:53 +0000

Serverless is a term we hear a lot in this industry, but what does serverless really mean? Serverless doesn’t really mean you don’t have servers, it’s more like servers as a service. Instead of owning and maintaining your own servers, you let a service do the work for you. You can focus on the business needs and developing a better quality application instead of worrying about the infrastructure and maintenance of a traditional server.

Serverless functions give developers superpowers and enables them to do things that would not otherwise have been possible. —Jason Lengstorf

Serverless Functions on Netlify

Serverless functions, branded as Netlify Functions when running on Netlify, are a way to deploy server-side code as API endpoints. These will spin up automatically when triggered by an event, handle and process server ran code, and then spin down until the next event. Using Netlify for your serverless functions creates a seamless workflow that allows you to write and test your functions locally with the Netlify CLI, build and deploy your applications, and avoid the setup, cost, and maintenance of a physical server.

On Netlify, there are several options when it comes to using serverless functions. This post is going to focus on traditional serverless functions, but you may also want to explore background functions or the new edge functions that can be distributed closer to your users.

Traditional Serverless Functions

What’s thought of as a traditional serverless function, is a short running synchronous function written in JavaScript, TypeScript, or Go that is hosted as an endpoint. It performs some server side code and then returns a response to the client immediately. These are AWS Lambda functions with a default region of us-east-1. They have a 10 second time limit and a memory limit of 1024 megabytes.

Everything that we do in technology has a tradeoff, there are pros and cons no matter what it is. Let’s look at both for serverless functions.

Pros

lowers barrier to entry for devs
inexpensive
faster iteration
quick deployments
abstracts away the setup and maintenance of a physical server

Cons

not built for long running processes (10 sec limit)
stateless - does not maintain data
cold starts - referring to the time it takes to start up when a function is invoked or ephemeral containers

Getting Started

Now we are going to walk through the steps to get a serverless function up and running on Netlify. To get started with this project, having some understanding of HTML, JavaScript, the command line, npm, and git will be helpful. Also, if you don’t already have a Netlify account, you can sign up for free here.

Project Setup

Open the explorers up and running with serverless functions repository on Netlify’s GitHub.
Click the Use this template button in order to create this repo inside of your own account.

Give your cloned repo a name and click the Create repository from template button.

Once you have created the new repository, click the Code button and copy the link to clone the repository.

Setting up the Project Locally

Open up a terminal to the location you want the project to be placed at, then run the git clone command and paste your link that you copied in the last step.
```
git clone https://github.com/brittneypostma/new-cloned-serverless-functions-repo
```
You can change directory with cd into your new project folder directly from the terminal or open your folder in your favorite code editor.
```
cd new-cloned-serverless-functions-repo
```
Currently there is only a [README.md](http://README.md) and .gitignore file and a public folder inside.

Netlify CLI

Now that you have the project cloned and up setup locally, we need to install the packages needed to run the serverless functions locally. First, make sure you have Node.js installed on your machine. You can check if you have it and what version by running npm --version. Now, we need to install the Netlify Command Line Interface, or CLI. Run the following command in the terminal to install it globally on your machine.

npm install netlify-cli --global

You can either use the netlify or the shorthand ntl to run cli commands. I’ll be using the shorthand versions for the remainder of the tutorial. Check the version you are running of the cli with ntl --version.

If you don’t already have a Netlify account, you can sign up for free here. Then you can login with the CLI by running ntl login and authorize the application.

Now we need to initialize the application by running ntl init and go through the steps to create a new site on Netlify.

Run ntl init and select Create & configure a new site.

Select the team you want to use.

Name your site or leave it blank for a random name.

The site is now created. You should see your admin URL, the main URL, and the site id listed in the terminal.

The CLI will prompt us for the build command, leave this blank and the CLI will fill in # no build command.

Fill in the directory to deploy as the public folder.

In this step, leave the default netlify/functions folder.

And since we haven’t created a netlify.toml file yet, in this step, enter Y to generate one with the settings you specified.

Once you see the Success! message, your site is ready to deploy. There are some next steps listed, git push to trigger a deploy or run ntl open to open your new site’s dashboard.

Anatomy of a Serverless Function

The basic anatomy of any serverless function has three basic parts. It must export a handler asynchronous function and then return an object with a statusCode and body property, which typically has a JSON object that needs to be converted to a string using the JSON.stringify() method for the message to be read.

export const handler = async () => {
    return {
        statusCode: 200,
        body: JSON.stringify({
            message: 'This is what will be returned!'
        })
    }
}

Project Overview

Now that the project is set up locally and linked to a Netlify url, we can start looking through the project.

index.html

Open up the directory you created in your favorite code editor and navigate inside the public directory to the index.html file and open it up.

If you look inside the <body> tag, you should see an <h1> tag, a <button> with an id="fetch-btn", and a <p> placeholder for the response. In the <script> tag below, there is an event listener that listens for a click on the button and inserts the response into the placeholder area.

netlify.toml

The next file to look at is the netlify.toml file that we setup with the Netlify CLI. The build settings should be set up as follows.


[build]
    command = "# no build command"
    functions = "netlify/functions"
    publish = "public"

[functions]
        node_bundler = "esbuild"

The directory for the functions defined in the toml file hasn’t been created yet. At the root of your project, create a new folder named netlify and another folder inside it named functions. The new project structure should look like this.

Creating Your First Serverless Function

Inside of the new netlify/functions directory, create a new file hello-world.js. Use the export syntax and create an async function called handler, that returns a statusCode of 200 and a body with the message that is stringified with the JSON.stringify method.

export const handler = async () => {
  return {
    statusCode: 200,
    body: JSON.stringify({
      message: 'Hello World!',
    }),
  }
}

Fetching the Response

Now, let’s configure the client side JavaScript we will use to fetch the response over in the index.html file. In the script tag below the markup, there is a fetchBtn event listener set up to listen for a click on the button in the markup. Here we need to make the function async, create a variable to fetch the serverless function endpoint, and return the response. One interesting thing to point out, is when we fetch the serverless function, we need to call it at the directory .netlify, with a dot in front of it. This is to avoid name collisions with other APIs.

fetchBtn.addEventListener('click', async () => {
  const response = await fetch('/.netlify/functions/hello-world')
        .then(response => response.json()
    )

  responseText.innerText = response
})

Once the function is setup, we can run ntl dev in the console to run the development server and test the function. Open up [localhost:8888](http://localhost:8888) in the browser, open the developer console, and navigate to the network panel.

When you click on the fetch button, you will see the hello-world call come into the network panel.

You can see the 200 status and if you click on the function and navigate to the Preview tab, you can see the object message of “Hello World!”.

You may notice the text is printing [object Object], this is because we need to stringify the response in the fetchBtn event listener function. Add the JSON.stringify(response) method and save the file.

fetchBtn.addEventListener('click', async () => {
  const response = await fetch('/.netlify/functions/hello-world')
        .then(response => response.json()
    )

  responseText.innerText = JSON.stringify(response)
})

If you reload the site and click the Fetch button again, now the message will display correctly.

Calling an API from a Serverless Function

External APIs can be integrated with a serverless function to grab data, that can then be used in the response. We are going to work with the Poke API, which allows you to get all kinds of information about the Pokémon world.

Creating a New Endpoint

Back in the code editor, we need to create a new file in our netlify/functions directory named pokedex.js that will house our new endpoint. This time, create a constant for the POKE_API url https://pokeapi.co/api/v2/pokedex/kanto, await the fetch call to the url, and create a new constant, data, and await the response.json(). Next, we’ll return the statusCode: 200, and stringify the data response in the body.

export const handler = async () => {
  const POKE_API = 'https://pokeapi.co/api/v2/pokedex/kanto'

  const response = await fetch(POKE_API)
  const data = await response.json()

  return {
    statusCode: 200,
    body: JSON.stringify({
      data
    })
  }
}

Fetch the Pokédex Endpoint

Back in the index.html file, first we will need to add a new button to fetch the pokedex.js endpoint we just created. Add a new button to the markup, with the id fetch-pokedex-btn and the text Fetch Pokedex.

<button id="fetch-pokedex-btn">Fetch Pokedex</button>

Next in the script tag, create a constant and add the element selector.

const fetchPokedexBtn = document.getElementById('fetch-pokedex-btn')

And finally, create a new event listener function for a click on the fetch-pokedex-btn to add the stringified data to the innerText of the variable set to the p tag.

fetchPokedexBtn.addEventListener('click', async () => {
    const response = await fetch('/.netlify/functions/pokedex')
        .then(response => response.json())

  responseText.innerText = JSON.stringify(response)
})

At this point, if you run the server with ntl dev, you will see both of the buttons we created, but the Fetch Pokedex button will return an error. Checking the network panel and the terminal for the issue, we’ll see a 500 error and an errorMessage: "fetch is not defined".

This happens because the serverless function running at the pokedex.js endpoint is on a Node.JS server. Node does not have access to the native fetch API provided inside the browser. As a result, we need to install a dependency that will allow us to run fetch on a Node server. Shut down the server with ctrl+C and follow the next steps to set up server-side fetch.

Initializing NPM

To install packages inside of our application, we need to create initialize this as a npm project. To do that, run npm init in the root directory of your project. This will walk through steps to create a package.json file. You can leave everything as default by hitting Enter through each step or change anything by typing it in and then hitting Enter. Once complete, it will ask you “Is this OK?” and you hit Enter for yes or type no if you wish to start over.

Once you say yes and hit Enter, a new package.json file will be created at the root of your project with the above information.

This file is responsible for keeping track of any dependencies and some basic details of the project.

ESM Support in Node

As of Node.js version 17.0.0, ESM, or ECMAScript modules, support became available in any Node.js application. Some libraries, like the one we will be installing next, have made the ESM migration. While you can use libraries with or without ESM, you can’t pick and choose the syntax you use. You must completely convert your application to ESM or stick with the old syntax. The original videos this tutorial is based on used the older syntax for the serverless functions. We have since updated the repo and this guide is using the newer ESM supported syntax. To convert over to ESM, add a "type": "module" to the package.json file and switch the exports.handler = async function () to const handler = async () =>. If you have any imports using the require() syntax, they will also need to be converted to import name from 'package' syntax.

Replace the CommonJS syntax:

const fetch = require('node-fetch')

exports.handler = async function () {

with the ESM syntax:

import fetch from 'node-fetch'

export const handler = async () => {

We also need to update the netlify.toml file to tell Netlify to use esbuild for the serverless functions when they are deployed. Add the setting node_bundler = "esbuild" under [functions]

[functions]
  node_bundler = "esbuild"

Installing Packages

Now that we have the package.json file created, we can install a Node fetch library. In the terminal, run the command npm install --save-dev node-fetch. Once it is completed, you will see a new devDependencies property with the node-fetch library in the package.json file and a new package-lock.json file created automatically.

Your version will probably look different than mine. If you run into any issues, try removing node-fetch with the npm rm node-fetch command and then install npm install --save-dev node-fetch@3.2.8 to install the save version.

Import Packages

Head back to the netlify/functions/pokedex.js file where we need to import and use the node-fetch library we just installed. We’ll need to use the import syntax, since version 3 and greater of the node-fetch library uses ESM syntax. Add this line to the beginning of the file.

import fetch from 'node-fetch

Don’t forget, you also have to update the package.json file with a "type": "module" property if you didn’t already to tell it to use ESM as well.

Now if you start the server again with ntl dev and navigate to [localhost:8888](http://localhost:8888) in the browser, you can see the function run successfully.

Deploying Serverless Functions

Earlier we setup and linked a site to Netlify with the Netlify CLI. Any time we make a push to the git repository that is linked to the Netlify site, a deploy will automatically trigger. Let’s go ahead and run the commands to push our code and trigger a deploy.

Shut down your server, if it isn’t already, with Ctrl+C.
Add all of the files with the git add . command, I have 7 changes to commit.

Commit the files with a message about what was changed.

git commit -m 'Set up a Netlify site with 2 serverless functions.'

Push the changes up to your git provider with git push or git push origin main.

That push will have set off a deployment on Netlify. You can run ntl open to open the Netlify dashboard linked to your site. Once there, you can click directly on the url to open the site or click on the Deploys tab to see the last deployment log.

To see the serverless functions we created, click on the Functions tab.

You should then see the 2 functions listed by the name of the files.

You can further click into each function to see the times and logs from when they were ran.

Customizing the Serverless Functions Request

Any serverless function can do stuff to the data before it returns to the frontend. It can be customized in whatever way you need it and only return the things you want to use. In our example the pokedex.js is returning all of the data about every Pokémon and wasting space on information we probably don’t need. Back in the pokedex.js file in your code editor, customize the data object being returned in the body to limit it to only the pokemon_entries.

import fetch from 'node-fetch'

export const handler = async () => {
  const POKE_API = 'https://pokeapi.co/api/v2/pokedex/kanto'

  const response = await fetch(POKE_API)
  const data = await response.json()

  return {
    statusCode: 200,
    body: JSON.stringify({
      pokemon: data.pokemon_entries
    })
  }
}

This will limit what is returned to just a list of the Pokémon without some of the extra data.

Fetching Different Data

Back in the index.html file, we’ll add another button and update our current one to grab 2 different types of data. Update the button with the id fetch-pokedex-btn to the id fetch-kanto-btn. Then add a new button with an id of feetch-hoenn-btn.

<button id="fetch-kanto-btn">Fetch Kanto Pokedex</button>
<button id="fetch-hoenn-btn">Fetch Hoenn Pokedex</button>

We’ll also need to update the variables and functions in the script tag. Replace the fetchPokedexBtn line with the new variables that grab the new ids.

const fetchKantoBtn = document.getElementById('fetch-kanto-btn')
const fetchHoennBtn = document.getElementById('fetch-hoenn-btn')

Next, we have to update the event listener functions to grab the different data types. First, update the name on the current fetchPokedexBtn event listener to be fetchKantoBtn. Now we can edit the data coming back by using the native fetch API, which takes an options object as a second parameter, to pass a POST method and send the custom data back to the serverless function. Here we want to specify the kanto region for the Pokémon API.

fetchKantoBtn.addEventListener('click', async () => {
    const response = await fetch('/.netlify/functions/pokedex', {
        method: 'POST',
        body: JSON.stringify({
            region: 'kanto'
        })
    })
        .then(response => response.json())

    responseText.innerText = JSON.stringify(response)
})fetchKantoBtn.addEventListener('click', async () => {
    const response = await fetch('/.netlify/functions/pokedex', {
        method: 'POST',
        body: JSON.stringify({
            region: 'kanto'
        })
    })
        .then(response => response.json())

    responseText.innerText = JSON.stringify(response)
})

We also need an event listener function for the “Fetch Hoenn Pokedex” button. We’ll do the same thing, but switch out the kanto region for hoenn.

fetchHoennBtn.addEventListener('click', async () => {
    const response = await fetch('/.netlify/functions/pokedex', {
        method: 'POST',
        body: JSON.stringify({
            region: 'hoenn'
        })
    })
        .then(response => response.json())

    responseText.innerText = JSON.stringify(response)
})

Event and Context Parameters

All serverless functions accept two parameters, event and context. The event object includes information about the request and the context parameter includes information about the context that the function was called in. We can use the event object to grab the custom headers we are sending along with the requests we added to our index.html code. In the pokedex.js file, add the two parameters to the handler function and log the event and context with console.log(event, context) I like to wrap the variables I am logging in an object, {}, to see the name when it comes through.

// pokedex.js
import fetch from 'node-fetch'

export const handler = async (event, context) => {
  console.log({event}, {context})
  const POKE_API = 'https://pokeapi.co/api/v2/pokedex/kanto'

  const response = await fetch(POKE_API)
  const data = await response.json()

  return {
    statusCode: 200,
    body: JSON.stringify({
      pokemon: data.pokemon_entries
    })
  }
}

Save the file and run ntl dev, click on one of the Fetch Kanto Pokedex button and in the terminal you will see a lot of data coming back. The important part here is the event.body, which you will see is the region of the Pokémon that we sent through the POST method.

We are going to use this information by creating a variable to hold the parsed event.body and then update the url that is fetched to dynamically update depending on the region sent.

import fetch from 'node-fetch'

export const handler = async (event, context) => {
  const eventBody = JSON.parse(event.body)
  const POKE_API = 'https://pokeapi.co/api/v2/pokedex/kanto' + eventBody.region

  const response = await fetch(POKE_API)
  const data = await response.json()

  return {
    statusCode: 200,
    body: JSON.stringify({
      pokemon: data.pokemon_entries
    })
  }
}

Now if you refresh the page and click the two Pokedex buttons, you will see two separate sets of data based on the region specified. You can add, commit, and push your code to git to kick off a new deploy of the site.

Next Steps with Serverless Functions

Great job! You have experienced how serverless functions can give developers superpowers to build and customize functionality in their applications. This allows you to solve business needs with a wider range of tools and techniques without needing to manage any infrastructure. Now there’s a whole realm of possibilities for you to explore with serverless functions. To learn more about how you can get the most out of serverless functions with Netlify be sure to check out the official docs where you can learn more about other solutions, such as background functions, which allow you to execute longer running scripts, using serverless techniques. I can't wait to see what you build with Netlify functions. Remember, if your experience is different from anything written here or something didn’t work as expected, please let us know about it here and we will help you or answer any questions you have.

How to Deploy the Qwik JavaScript Framework

Brittney Postma — Wed, 22 Jun 2022 10:37:47 +0000

In this tutorial, I will show you how to deploy a Qwik application on Netlify. There is a great step-by-step guide to deploying on Netlify for general use, but this guide is specifically to show you how to deploy Qwik applications.

What is Qwik

Qwik is currently in Beta at the time of writing and may have changes. It is being developed by Miško Hevery and the team at Builder.io.

Qwik is a resumable JavaScript framework that renders server-side HTML to optimize performance. It completely removes the hydration step that other frontend frameworks use. The core principle of Qwik is to load as little JavaScript up front as possible and delay the execution of any other JavaScript on the page until it is needed. This allows the application to progressively download code without a big bundle right away. To make this work, Qwik uses an Optimizer written in Rust to transform the code at build time. Vite is used for Hot Module Replacement (HMR) and bundling code.

Qwik Rendering

Rendering on the web has swung like a pendulum from completely server-side to all static. We now have frameworks that can do hybrid rendering like Next.js and SvelteKit. However, because Qwik needs to progressively load JavaScript to improve the performance, it needs to be able to grab that from a server or server-side rendering (SSR). This may not fit into the true Jamstack architecture, but that doesn’t mean it can’t be hosted on Netlify. Platforms like Netlify can take the server side code and use it as serverless or edge functions. This is typically done with some type of adapter or plugin during the build step. In Qwik’s case, it uses the Netlify Edge functions with a Vite plugin. Read more about Netlify Edge here.

Getting Started with Qwik

The quickest (pun intended 😁) way to get started with a Qwik app that will be deployed to Netlify, is to use the command line interface — or CLI — tool. Type the following into a terminal to start the Qwik CLI.

npm init qwik@latest

This command opens the CLI that will prompt you with the following.

Qwik CLI

Choose your project type, we are choosing a blank starter app to keep it simple.

Choose Netlify as your hosting provider.

Select packages you want configured automatically. Eslint and prettier for linting and code formatting, TailwindCSS is an option for styling.

Success! Your Qwik app is created. Follow the next steps to install the dependencies and run the project locally.

Running the Qwik App

Once you have completed the steps in the CLI, change directory (cd), into your newly created project and install the dependencies with a package manager. The Qwik CLI suggests using npm.

cd qwik-app-name
npm install  # or yarn or pnpm

Then you can run the dev server to see the site locally with the npm start command.

npm start  # or yarn or pnpm

Starter Application

Once through the steps of creating the application and installing the dependencies, you are on your way to deploying the app. If you used the CLI and chose Netlify as the hosting provider, a netlify.toml file already setup for you. If you happened to start here, you can create a netlify.toml file in the root that has the code below in it.

[build]
publish = "dist"
command = "npm run build"

Deploy Qwik Applications on Netlify

Netlify is a web developer platform that is known for making the web better by increasing productivity. If you are not already a Netlify user, go ahead and sign up for free. There are two ways we can deploy a Qwik site to Netlify, the Netlify CLI or a manual git deploy.

Netlify CLI deploy

The Netlify CLI is a way to configure, build, test, and deploy your sites without leaving the command line. If you don’t have the Netlify CLI installed, run the following command to install it globally.

npm install netlify-cli -g

Once installed, many commands can be ran with either the netlify {command} or ntl {command} for short. First, run the netlify login command to authenticate your Netlify account to the CLI. This will open a browser window, asking you to log in with Netlify and grant access to Netlify CLI.

To setup a new site using the CLI, run netlify init. This will guide you through the steps to get your site connected and deployed.

If you don’t have your app connected to git, the Netlify CLI will ask if you want to deploy it manually or connect to a repo. Deploying manually will add more steps, to avoid this you can add your site to a git provider before running netlify init.

Either connect to an existing Netlify site, or create and configure a new site.

Choose the team you would like to add the site to.

Name your site or leave it blank for a random name. Once this is done, your site is created and your links are available, but the site is not yet deployed.

Netlify will attempt to detect the build command and directory of the output for the app, but it can be customized in the next steps. For Qwik apps they are:

Specify your functions directory if you are using Netlify functions.

And success, your site is deployed!

Once configured, any new push to your git repository, git push, will trigger a new site build or by running netlify deploy --prod. Running netlify open will open the Netlify admin URL for your new Qwik app on Netlify!

Deploy a Qwik Site from Git

If you choose to do so, you can also manually deploy a Qwik app on Netlify. Once you have a git repository pushed, navigate to the Sites page in your Netlify dashboard and click the button “Add new site”.

A dropdown menu will appear that asks if you want to import an existing project, start from a template, or deploy manually. To get a site from git, you should choose the Import an existing project option.

That will bring you to a screen to connect your Git provider.

Choose the provider where the git repository for your app is located, then Netlify will authenticate and pop up a search for your available repos. Choose your repository, and Netlify will auto detect the framework and populate the build command and publish directory. If there is a custom build, you can edit the settings on this screen.

Click the Deploy site button and Netlify will begin deploying your application. Now your Qwik app is live!

That’s it, now you have a Qwik app deployed to Netlify. Remember, if your experience is different from anything written here or something didn’t work as expected, please let us know about it here and we will help you or answer any questions you have.

How to Deploy SolidJS

Brittney Postma — Fri, 10 Jun 2022 14:08:30 +0000

Deploy SolidJS on Netlify

In this guide, we will show you how to deploy a SolidJS application on Netlify. Whether you are starting from scratch or switching from another platform, we have you covered when deploying Solid. There is a great step-by-step guide to deploying on Netlify for general use, but this guide is specifically to show you how to deploy Solid applications.

What is SolidJS

SolidJS is a reactive JavaScript library that uses declarative JSX code to create performant user interfaces. Solid follows many of the same philosophies React does and has an API similar to React Hooks. Rather than using a Virtual DOM as React does, Solid compiles its components into actual DOM nodes that update in a more performant manner with more precision.

Deploy Solid Applications to Netlify

Netlify is a web developer platform that is known for making the web better by increasing productivity and deploying the fastest applications using the Jamstack architecture. If you are not already a Netlify user, go ahead and sign up for free first.

Otherwise, feel free to go directly to whichever section is most relevant to you:

Drag and Drop deploy - no git repository needed
Netlify CLI deploy
Manual Deploy from Git

Getting Started with Solid

The quickest way to get started with a Solid app, is to use the base template. Type one of the following into a terminal.

JavaScript Template

npx degit solidjs/templates/js my-app
cd my-app
npm i # or yarn or pnpm
npm run dev # or yarn or pnpm

TypeScript Template

npx degit solidjs/templates/ts my-app
cd my-app
npm i # or yarn or pnpm
npm run dev # or yarn or pnpm

Drag and Drop deploy with Netlify

With the new Drop deploy, you don’t even need a git repository to deploy your site. Within the terminal from the location you created your app, run the build command for the Solid app.

npm run build # or yarn or pnpm

The dist folder is then created within the root of your project. Navigate to the folder that holds your new dist folder in your Finder on Mac or File Explorer on Windows devices and also go to your Netlify team page and login. Once you are logged in, you can drag your dist folder right onto the page and Netlify will generate a url and quickly deploy your Solid site.

Netlify CLI deploy

The Netlify CLI is a way to configure, build, test, and deploy your sites all without leaving the command line. First, you need to have the Netlify CLI installed on your local machine. Run the following command to install it globally.

npm install netlify-cli -g

Once installed, many commands can be ran with either the netlify {command} or ntl {command} for short. First, you will want to run the netlify login command to authenticate your Netlify account to the CLI. This will open a browser window, asking you to log in with Netlify and grant access to Netlify CLI. You can then use the netlify init command to either connect a site without a git repository or connect your local repository for continuous deployment on Netlify. This will lead you through a few steps to get your site connected and deployed.

If you don’t have your app connected to git, the Netlify CLI will ask if you want to deploy it manually or connect to a repo. Deploying manually will add more steps, to avoid this you can add your site to a git provider before running netlify init.
Once connected to git, either connect to an existing Netlify site, or create and configure a new site.
Choose the team you would like to add the site to.
Name your site or leave it blank for a random name. Once this is done, your site is created and your links are available, but the site is not yet deployed.
Netlify will attempt to detect the build command and directory of the output for the app, but it can be customized in the next steps.
Specify your functions directory if you are using Netlify serverless functions and create a netlify.toml configuration file if you don’t already have one.
And success, your site is configured!
To deploy your site, run netlify deploy in the terminal. Or head to the app.netlify.com dashboard to deploy manually.

Once configured, any new push to your git repository, git push, will trigger a new site build or by running netlify-deploy --prod. Running netlify open will open the Netlify admin URL for your new Solid site!

Deploy a Solid Site from Git

You can also manually deploy a Solid app on Netlify. Once you have a git repository pushed, navigate to the Sites page in your Netlify dashboard and click the button “Add new site”.

That will bring you to a screen to connect your Git provider.

Search the provider where the git repository for your app is located, then Netlify will authenticate and pop up a search for your available repos.

Once you choose the correct repository, Netlify will auto detect the framework and populate the build command and publish directory. If there is a custom build, you can edit the settings on this screen.

Click the Deploy site button and Netlify will begin deploying your application. Now your SolidJS app is live!

That’s it, three different ways to deploy your SolidJS site to Netlify. Remember, if your experience is different from anything written here or something didn’t work as expected, please let us know about it here and we will help you or answer any questions you have.

The Acronyms of Rendering on the Web

Brittney Postma — Wed, 01 Jun 2022 17:01:27 +0000

Many frontend frameworks now offer the ability to choose how you want to deliver your website to users. Each will give the user a different experience depending on the way it is rendered. First, let’s break it down. What is rendering?

What is rendering

Rendering is the process that turns the code you write an application in into something that users can interact with on a web page. Declarative code, even plain HTML files, cannot just be plopped into the browser and work properly. When a user requests a website it needs to be parsed into something usable by the JavaScript engine inside the browser before anything is rendered on the screen. The code has to be transformed before it can even start the process of the Critical Rendering Path (CRP). These are the steps the browser takes to convert your code into actual pixels on the screen including the Document Object Model (DOM), CSS Object Model (CSSOM), the render tree, and layout.

Types of rendering

When a user navigates to a website, a request is sent off to a server and data is returned before the CRP begins. How that data gets returned is the type of rendering that occurs. There are three different types. These include Client Side Rendering (CSR), Server Side Rendering (SSR), and Static Rendering or Static Site Generation (SSG). Each will change the user experience of the website and how the performance or perceived performance is optimized. Many frontend frameworks give you the option to choose how to render different pages on your site.

Client Side Rendering (CSR)

Client Side Rendering or CSR lets the browser do as much of the work as possible to render the page. The "client" is the current browser being used to view the site. Initially a request is sent to the server and a single HTML file with any JavaScript that is needed to load the rest of the site is returned. If your site contains JavaScript, then it will be ran completely inside the browser from that point on. Even plain HTML and JavaScript sites without a framework will be rendered on the client (CSR). Sites that use CSR commonly have a loading spinner or some indication that you are waiting on content to load. By delaying the initial load, once the site is on the screen everything is fully interactive and functional. In most cases, this requires extra JavaScript to be ran and can be hard to keep performant at scale.

Server Side Rendering (SSR)

Server side rendering, SSR, is what the web of old was built on. Trends went far in the opposite direction with CSR with single page applications (SPAs) and popular libraries like React. Now SSR is starting to fall back into style. This puts most of the work back on the server. When the browser requests a page, the server builds the page, compile all the data, and return the entire HTML page back. Data is dynamically grabbed from the server every time a user visits the page. This causes the server to do the work all over again. Internet speed, server location, and too many users at once can impact the performance of these sites.

SSR has become the new trend because Content Delivery Networks (CDNs) like Netlify, provide servers across the globe that distribute the content closer to the end user. That request to response trip is shorter in most cases than the traditional single server location. This is also where the term serverless comes in. You are able to build and deploy your applications without having to maintain the actual server infrastructure. SSR uses serverless functions under the hood on the Jamstack. On Netlify, serverless functions default to use a single server location. Static pages are still served from the CDN and SSR can be ran on the CDN with Edge Functions.

Static Rendering / Static Site Generation (SSG)

Static rendering is when all of the data a page needs is generated when the site is built. Prerendering all of the content in your site emerged with frameworks like Jekyll and Gatsby. These sites do all of their data collection at build time and is cached at that moment in time. Any new data that changes on the site requires a rebuild of the entire application. This built the foundation for the original concept of the Jamstack architecture, a web development workflow that focuses on prerendering as much content as possible. Additionally making them dynamic through application programming interfaces (APIs) and serverless functions. Having to rebuild the entire site for any change led to long build times and new solutions emerged to lessen these.

Rendering Techniques

As sites started going in the direction of more prerendered content and build times started creeping up, new techniques were developed to help combat them. These focused on increasing the speed and the functionality of sites built on the Jamstack.

Distributed Persistent Rendering (DPR)

Distributed Persistent Rendering (DPR) allows developers to defer the rendering of a route or asset until the first time a user visits the page and is then cached on the CDN. This sacrifices the load time somewhat for a single user to lower the build speed and have the newest content available. With this technique the most visited pages can be prerendered at build time and less popular pages can be built on-demand. When the page is built on demand, the cached page is immediately invalidated. That means if there is ever a need to rollback to a previous build, users would never see stale content.

Incremental Static Regeneration (ISR)

Another technique that came from Next.js, a React framework, is Incremental Static Regeneration (ISR). Rather than deferring the rendering of the page, it is rendered at build time and cached. When a user requests the page, the cached page is shown for a time while a new build of the page is triggered in the background. The cached page is not invalidated until the new page is generated.

Edge Rendering

Edge rendering is a new term that is popping up everywhere. Most of this comes down to serving things at the CDN level, the “edge”. This piece comes in when a page has already been rendered and needs to be updated with personalization or locale data giving atomic updates to your application. There are a handful of vendors offering this in some form, but each has their own flavor. Netlify uses Deno, a runtime based on modern web standards, rather than Node.js for their implementation.

Wrapping up

There are many choices when it comes to getting a page to a user and each comes with its own implications. It comes down to choosing the tool that is right for the job, but don’t be stuck in decision paralysis. One way to test if you need SSR or CSR is to disable JavaScript and load the web page. If your page is still functional, it can likely be prerendered. Using the Jamstack architecture allows you to start small and add in complexity where it is needed. Prerendering as much content as possible and using less JavaScript is better for everyone. Increased performance, portability, and maintainability are just a few of the reasons why to use the Jamstack.

Accessibility Best Practices for HTML & CSS

Brittney Postma — Thu, 19 Aug 2021 14:52:01 +0000

Additional Links
Foundation
Semantic HTML
- Structural
- Content
- Language
- Forms
Styling
- Contrast
- States
- Animations

Accessibility Best Practices for HTML & CSS

Great accessibility is not always an easy task and goes much more in depth than what is listed here. I still recommend having experienced screen readers and accessibility experts test your site and run your site through the WebAIM Web Accessibility Evaluation Tool, WAVE. If you see anything that should be added, updated, or removed, please get in touch with me either in the comments or @brittneypostma on Twitter. This article is here to serve as a starting point to summarize and guide your way to better accessibility. Having better accessibility isn't only the right thing to do, it also increases your Search Engine Optimization, SEO, which can rank you higher in Google's algorithm. Here are some links to provide more information on web accessibility.

Additional Links

Foundation

Everything should start with a good foundation and with Hypertext Markup Language, HTML, that is the structure of your page. A huge part of web accessibility is just making sure the HTML elements are used correctly. A web page may be styled in many different ways to organize information visually, especially with different viewport sizes, but a blind user only hears the order defined in the HTML of a page. In my opinion, using semantic HTML along with mobile-first design allows you to see the layout of a page linearized into one column and the order of the markup to see if it makes sense.

Semantic HTML

The word semantic relates to the meaning of something in a language or logic. In semantic HTML the HTML element used gives meaning to define its content and how it is classified. There are currently over one hundred different elements in HTML, but not all of them have a semantic meaning. The layout of the page defines the page regions that are identified by web browsers and assistive technologies.

Structural

Use the header and footer elements to define the top and bottom of a page, but also can define the top and bottom of an article or section.
Use the nav element for major blocks of links to allow assistive technologies to quickly and easily navigate through the site. Thenav element can be used around unordered lists, ul, or around a block of content referring to multiple links. You can use the aria-label property to identify different navigation areas.
Use the main tag to define the main content of the page and aside to define anything related to the main content.
Only use divs and spans for styling purposes. Use the section tag to group related elements with a heading and the article tag to group a self-contained item that is independent or reusable. The article element can be posts, news articles, product cards, comments, or any other form of independent items or content. Here is a great Smashing Magazine article on Why You Should Choose HTML5 article Over section explaining that article can be used in almost all instances, but a section with an aria-label can be helpful.

Content

Use the correct levels for headings, from the most important as an h1 down through h6 and do not skip heading levels. Each page should have a heading level 1, h1 , that represents the most important idea on the page. Any sub-headings should be an h2 , sub-sections can then be divided into h3s and on down to h6 s based on the nested structure.
Use the paragraph, p, element to wrap self-contained blocks of text that focus on a single topic or theme. Also, the strong and emphasized, em, elements have semantic meaning where bold, b, and italic, i, are simply style differences.
Use an alt attribute on images if the image is important to the content, such as information to understanding or interacting with something. Otherwise, if an image is decorative and adds no value to the content, the attribute can be declared alt="" and it will not be read by assistive technologies.
Try to provide alternative to audio and video content, such as captions or transcripts for those that are hard of hearing or using screen readers.
Use the anchor, a, tag for links that go somewhere else and the button tag for an action like submitting a form or a click event.

Language

Don't use dashes if you can avoid it. Instead of writing 5–7, write 5 to 7.
Expand abbreviations — instead of writing Jan, write January.
Expand acronyms, at least once or twice. Instead of writing HTML in the first instance, write Hypertext Markup Language.

Forms

Forms are one of the most common problems for accessibility on sites. Make sure not to disable any of the default keyboard functionalities or tab order and use the proper markup. Also, consider keeping forms short and only ask users for the minimal information needed to complete the process. https://www.w3.org/WAI/tutorials/forms/
Use the label element with a for attribute that matches an id attribute on the accompanying input or wrap the label around the input. https://www.w3.org/WAI/tutorials/forms/labels/
Make sure instructions needed to complete an input are listed before the input area and make clear if an input is required and any validation requirements. Make any errors that prevent completing a form known to the user.

Styling

Styling, whether with CSS or JavaScript, can cause accessibility issues to occur when some browser defaults are removed or incorrectly changed. Including heading and text sizes, outline styling, color contrast, and more. The best practice is to leave the browser defaults if you don't know how to correctly restyle them. I've listed some of the most common issues below. https://developer.mozilla.org/en-US/docs/Learn/Accessibility/CSS_and_JavaScript

Contrast

There should be sufficient contrast between any foreground text and the background color behind it. The minimum contrast ratio for normal sized text is 4:5:1 and 3:1 for larger text. These are AA minimum contrast criteria.
There are enhanced AAA criteria at 7:1 for regular text and 4:5:1 for larger text. There are many extensions and plugins that check for contrast issues, but they can be inaccurate and inconsistent. The WebAIM provides a contrast checker at https://webaim.org/resources/contrastchecker/.
For non-text items the contrast ratio should be a minimum of 3:1.

States

The focus state shows when a user is focused, either by click, keyboard, or voice, on an element. Only interactive elements need to have a focus state. A common practice is to remove the default outline for focus states with CSS, never do this without replacing it. A background should be 3:1 contrast ratio for buttons and inputs and a minimum 1.4.3 underline for links. More information and examples are listed here https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html.
The hover and active states are sometimes styled similarly. The active state shows when something is activated, usually a button or a link, and the hover shows when it is being hovered on. The styles are not the important part for accessibility on these elements, but telling assistive technologies when an element is active is important. Using the correct aria-pressed attribute based on the state will tell a user whether the element is active or not. More info on states can be found here https://www.w3.org/WAI/tutorials/menus/styling/#hover-and-focus-states.

Animations

Users should be able to control any moving, flashing, or blinking content on a page. Examples include ads, videos, auto-updating visuals, moving backgrounds, and more. Basically, anything that is initiated by the page without the user interacting with it. A good practice is to use a prefers-reduced-motion media feature to turn off animations. If the animation is critical to understanding something, add it back in with a selector after turning down all animations. https://css-tricks.com/revisiting-prefers-reduced-motion-the-reduced-motion-media-query/

@media screen and
  (prefers-reduced-motion: reduce), 
  (update: slow) {
  * {
    animation-duration: 0.001ms !important;
    animation-iteration-count: 1 !important; /* Hat tip Nick/cssremedy (https://css-tricks.com/revisiting-prefers-reduced-motion-the-reduced-motion-media-query/#comment-1700170) */
    transition-duration: 0.001ms !important;
  }
}

Make sure all animated content has pause, stop and hide capabilities and check the tab order to ensure it works correctly. The Dark Side of the Grid is a good post on how changing visual order can mess with the order in the Document Object Model, DOM. The Accessible Web Animation Explained post from CSS Tricks has some good tips as well.
Do NOT have anything that flashes more than three times in a one second period as this is known to cause seizures. If you can't avoid flashing animations, see the W3C's detailed guide on how to meet the safe thresholds.

By no means is this the be all, end all of things that should be done for accessibility. It is an ongoing, ever-evolving process that is an extremely important aspect for inclusion and usability. These are some of the core fundamentals of good User Experience, UX, and helping others understand, navigate, and interact with your site. At a bare minimum, follow these best practices and run your site through the WebAIM Web Accessibility Evaluation Tool, WAVE. If you see anything that should be added, updated, or removed, please get in touch with me either in the comments or @brittneypostma on Twitter.

Make Pathing Easier with Aliases in SvelteKit

Brittney Postma — Thu, 05 Aug 2021 00:08:14 +0000

UPDATE June '22:
SvelteKit Alias Docs were updated with an improved way of configuring aliases. Aliases can now be configured as top level under the kit property in the svelte.config.js file. This article is now updated to reflect this change.

const config = {
  kit: {
    alias: {
      $components: 'src/components',
      $utils: 'src/utils'
    }
  }
};

If you haven't heard about SvelteKit yet, go checkout the beautiful site over at kit.svelte.dev. SvelteKit is a component framework similar to React and Vue with one key difference, there is no virtual DOM. Svelte is a compiler that builds itself away into a sleek and fast end user experience. If you haven't tried Svelte or SvelteKit before, you can check out my quick intro tutorial where we build a blog in 30 minutes 🤯

Links:

TLDR: To setup an alias add the following lines to the svelte.config.js. For the code editor you are using to understand the alias, we also need to add to the jsconfig.json paths with the aliases you want to create.

//svelte.config.js
import path from 'path'
const config = {
    kit: {
        alias: { 
            '@components': path.resolve('./src/lib/components'),
                    '@lib': path.resolve('./src/lib'),
                    '@utils': path.resolve('./src/lib/utils')
                }
            }
        }
    },
}
export default config

// jsconfig.json
{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
             // name and path to aliases
            "@components": ["src/lib/components"],
            "@lib": ["src/lib"],
            "@utils": ["src/lib/utils"]
        }
    },
    "include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte"]
}

Default Starter

To start a new SvelteKit project run npm init svelte@next app-name into the terminal where you want the folder to live. Change directory into your new app, cd app-name and run npm i to install the dependencies. Out of the box SvelteKit provides a $lib alias setup for the src/lib folder and a number of modules are available from $app and $service-worker. Outside of those, it is up to us to set up our own aliases and preferences on how to use them. These all use the $ syntax to use it, however, we are able to change the lib folder to @ or other symbol if preferred.

Change default alias

To update the default $lib alias to @lib, we need to tell vite that we want to use it by updating the svelte.config.js and the alias will work in our application. For the code editor to understand the alias, we need to edit the jsconfig.json file. Inside the svelte.config.js by default we see this setup.

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    // hydrate the <div id="svelte"> element in src/app.html
    target: '#svelte',
  },
}

export default config

Inside of the kit property, we need to add a an alias property to hold the aliases we are setting up. I prefer the @ symbol rather than the default $ and will show how to setup the @lib, @components, and @utils aliases. We need to import the included path module from node at the top and add the alias property under the kit property. The new svelte.config.js will look like this.

//svelte.config.js
import path from 'path'
const config = {
    kit: {
        alias: { 
            '@components': path.resolve('./src/lib/components'),
                    '@lib': path.resolve('./src/lib'),
                    '@utils': path.resolve('./src/lib/utils')
                }
            }
        }
    },
}
export default config

Next, we also need to set them up inside the jsconfig.json file. By default that looks like this.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
  // here is the default $lib setup by SvelteKit
      "$lib/*": ["src/lib/*"]
    }
  },
  "include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte"]
}

As you can see, the default $lib is added to this config already. We need to update that and add the paths for our other two aliases. The updated file will look like this.

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@components": ["src/lib/components"],
            "@lib": ["src/lib"],
            "@utils": ["src/lib/utils"]
        }
    },
    "include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte"]
}

Under paths we have added the @components, updated the $lib to @lib, and added @utils with the corresponding paths.

Using the aliases

Now we need to use the aliases inside of a file. The skeleton starter doesn't come with any folders outside of the routes folder for the routes of the application. If you chose this option, you can simply add the lib folder inside of the src folder to use the @lib alias. The other paths and aliases we setup are nested inside the lib folder. Add a components folder and utils folder inside of the lib folder. The folder structure should look like this.

src
  - lib
    - components
    - utils
  - routes

Now any files created inside of lib, components, or utils can be imported using the alias rather than having to type out the absolute path, like so.

<script>
import FileName from '@lib/FileName.js`
import ComponentName from '@components/ComponentName.svelte'
import UtilName from '@utils/UtilName.js`
</script>

And that's it 🥳 now you can use all of the aliases we created or create more of your own. I'm @brittneypostma on Twitter if you have more questions or just want to chat about Svelte 😃 Cheers!

CSS Grid Basics and Responsive Web Design Preview

Brittney Postma — Tue, 10 Nov 2020 13:40:50 +0000

Responsive Layouts & Design

TLDR This post has codepens and interactive content that cannot be added on dev. For the best viewing experience, visit The Console Logs - Responsive Web Design or see the full workshop at ZTM Academy - Responsive Web Design Workshop.

Table of Contents

Responsive Layouts & Design
Basic Design Principles
- Mobile First Design
- Fluid Grids & Relative Units
- Media Queries
Flexbox vs Grid
Grid Basics
- Gap
- Placement
- Self
- Explicit Grid
- FR Unit
- Functions
- Fill vs Fit
- Workshop

Hello, I'm Brittney Postma and I am happy to announce that I am joining the other amazing instructors at the ZTM Academy! I did a live workshop on Responsive Web Design that is available to all Academy students now! This article previews the workshop and gets you started on creating a beautiful and fluid web page.

"Every person, no matter what screen they are on, deserves a great user experience."

Basic Design Principles

What makes a good design? A good design should attract attention. Make it interesting and have a clear message that is present throughout the design. Have a consistent balance in margins and paddings to allow the eye to flow down the page. Then, when we break the rules (yes, there's a time to break the rules), it really makes a statement. There are 3 basic principles that I follow when creating responsive design. I start with the mobile design of the page, then create fluid grids and use relative units, and then add in media queries to adapt my layouts.

Mobile First Design

By starting with the mobile view of a website, we can see what is actually necessary for the design and clutter that needs to be cut out. The layout is usually simpler and allows us to visualize the content at a small scale. Mobile sites also tend to have more usability issues with touch inputs and swiping. By starting with the mobile view, we can address these issues before they become a problem.

Fluid Grids & Relative Units

Using modern CSS tools, we can create grids that flow as a screen gets larger. We take advantage of the powers of Flexbox and Grid to their full potential. Along with those, we use relative units throughout our design. Instead of basing everything on the inflexible pixel, we can use a range of units like vw, vh, rems, ems, ch, and percentages that create a fluid page that looks great on any device.

Media Queries

There are far too many screen sizes today to worry about creating a design for each screen. With mobile first design, media queries are only used to adapt the layouts. By using a breakpoint only when an element needs to be adapted, rather than the size of the users screen, we reduce the amount of media queries and create a more fluid page. I write all of my base css to style the mobile view of the page and then use a min-width: 768px and min-width: 1024px breakpoints to change the grids in certain elements. This means less code I have to write and a more beautiful page.

Flexbox vs Grid

A question that keeps getting asked is should I use Flexbox or Grid? The answer is both! We should stop thinking about them as if we are choosing between frameworks like bootstrap or tailwind. Think about the pattern you need for the layout and use them in conjunction with one another. Flexbox is a one-dimensional system, it works either in a column or a row but not both. They are content-first and work well when distributing space and aligning content. Grid is two-dimensional working in both rows and columns. It is layout-first and works well on large scale layouts that aren't linear. Grid also allows you to define areas and the relationship between them. You can even next a grid in a flex container or the other way around.

Which layout method do you use the most?

a. CSS Grid

b. Flexbox

c. Tables

d. Floats

Grid Basics

What happens when we put display: grid on an element? At first glance, it looks like nothing changed. Well, that's because it is shorthand for display: block grid. There is a lesser used rule, display: inline-grid that would create an inline grid that is only the width of the content inside of it. Just by using display: grid on an item makes it a grid container and we get access to all the other grid properties. Plus it makes all of the children grid items that become part of the grid layout. At this point, we just have an implicit grid. To create a layout, we would need to define some columns and rows. By using grid-template-rows and grid-template-columns we can explicitly define that layout of the grid we want. Anything that falls outside of that, is still going to follow that implicit grid. Check out the codepen below and uncomment some of the properties to see how the grid changes.

See the Pen CSS Grid Starter by bDesigned
(@bdesigned) on CodePen.

Gap

Gap allows us to define the spacing or gutters between the items. The gap property, previously grid-gap, was renamed since it was added to the Flexbox spec as well. It can be defined for both rows and columns with gap or used as row-gap and column-gap to differentiate between the two.

Placement

Placement in grid at first glance can seem complicated, but let's break it down. There are two base properties for each axis, justify and align, then content places the container, and items places each grid item. The justify property is along the inline axis, or horizontal in grid. The align property is along the block axis, or vertical in grid. We can then combine justify-content and justify-items to place either the grid container or each item along the horizontal axis. Also, align-content and align-items can be used to place the container or each item along the vertical axis. Here's a list to visualize it.

◾ justify-content - places the container along the inline axis, horizontal in grid. Options are start, end, center, stretch, or space-around.
◾ justify-item - places each item/child along the inline axis, horizontal in grid. Options are start, end, center, or stretch.
◾ align-content - places the container along the block axis, vertical in grid. Options are start, end, center, stretch, or space-around.
◾ align-items - places each item/child along the block axis, vertical in grid. Options are start, end, center, or stretch.

If you want to place the container or items into the same place along both axes, the shortcut place-content or place-items can be used. For example, putting place-items: center on the grid will perfectly center each grid item and place-content: center would center the container based on the width and the height.

Self

Along with placing the entire grid container or the items as a whole, each child or grid item can define where it should be placed in the grid with justify-self or align-self.

.grid {
  display: grid;
  gap: 1rem;
}

.grid-item {
  /* place at the end of the inline/horizontal axis */
  justify-self: end;
  /* place at the end of the block/vertical axis */
  align-self: end;
}

There is also the ability to span a grid item across grid columns or rows.

.col12 {
  /* span across 12 columns */
  grid-column: span 12;
  /* span down 2 rows */
  grid-row: span 2;
}

.col6 {
  grid-column: span 6;
}

.col4 {
  grid-column: span 4;
  grid-row: span 2;
}

.col2 {
  grid-column: span 2;
}

Explicit Grid

Everything we have talked about so far has fallen into the implicit grid, we never defined what we wanted our grid to look like. The properties that do this are grid-template-columns and grid-template-rows, or grid-template is the shortcut with rows / columns as the value. These are declared on the grid container and define what size of and how many columns and rows are wanted. Any unit can be used to define the size of each column and row. These create tracks, the space between two grid lines,

FR Unit

Grid also gives us access to another unit only useable in a grid container, the fr unit. The fr unit is short for fractional unit. Each fr unit defined is a fraction of the total size of the parent container. So if we had grid-template-columns: 1fr 2fr 1fr, the first column is 1/4, the middle column would be 2/4 (or 1/2 reduced), and the last column would be 1/4 of the size. The first and last column would be the same size and the middle column would be double the size of those.

Functions

There are functions that are only accessible in grid as well, the repeat() and minmax() functions are useable while defining the columns and rows. The repeat(quantity, size) function takes 2 arguments, the quantity and size for either grid columns or rows. The minmax(min-value, max-value) function also takes 2 arguments, but allows a minimum value and a maximum value to be defined for the columns and rows.

Fill vs Fit

Another concept used only in grid is auto-fill and auto-fit. These are used with the repeat() function and tell the grid algorithm to either automatically fill in more tracks or fit all the grid items across the container. This image shows what happens to the tracks between auto-fit and auto-fill.

In fact, all of these things can be combined and used together into what is commonly referred to as the "ram" function. That allows us to say either grid-template-columns: repeat(auto-fill, minmax(min-size, max-size)) or grid-template-columns: repeat(auto-fit, minmax(min-size, max-size)) depending on which layout method you want. This can be an extremely powerful function in making a layout responsive in one line of code. Here is a codepen showing auto-fill, auto-fit, and the ram function with auto-fit. Here is a codepen that shows the difference between ram with auto-fit and auto-fill.

See the Pen fit, fill, ram by bDesigned
(@bdesigned) on CodePen.

Workshop

Thank you for reading, I really hope this helped clear up any confusion with grid basics. There is so much more that we dive into in the workshop, creating a full responsive website using these concepts. It is focused on teaching you how to deliver a fluid, consistent design using modern CSS tools and responsive web design best practices. By the end of the workshop, you will be able to make that happen!

The CSS Podcast: Episode Four - The Cascade

Brittney Postma — Mon, 26 Oct 2020 16:43:56 +0000

Hi, I'm Brittney and I'm an instructor over at ZTM Academy and the owner, designer, and developer at bDesigned. You can find more dev notes by me at Console Logs.

MDN on Cascade and Inheritance
CSS Cascade Interactive Article

The "C" in CSS stands for cascade. Basically, this means that location and order matter when you are writing CSS rules. If rules have the same specificity, the one that is used last in the stylesheet will be used. The cascade is made up of 4 phases:

1. Position - The position of a rule with the same specificity in a stylesheet or where it is linked in the html matters. The one that appears last with the most specificity wins. An embedded style tag in the html and inline style are more specific than the stylesheets. You can think about their proximity to the code they are affecting; inline is the closest, then style tag, then linked styles, then browser.
2. Origin - Where the rules are coming from, 1st link tags, 3rd party link tags, embedded styles, inline-styles, browser (user-agent styles), client set styles
3. Specificity - user agent, client styles, your styles, your !important, client !important, user-agent !important
4. Importance - Depends on the type of rule and is in order from least to most specific; normal, animation, !important, transitions.

Updated with Hooks How To GraphQL with React Apollo

Brittney Postma — Wed, 26 Aug 2020 16:35:10 +0000

Hi, I'm Brittney and I'm an instructor over at ZTM Academy and the owner, designer, and developer at bDesigned. You can find more dev notes by me at Console Logs.

How To GraphQL Updated Tutorial Part 1

Frontend Setup
Into the code
- index.js
- Server
- Frontend
- GraphQL Query
- Mutations
- React Router
- Header

TLDR: The How To GraphQL with React Apollo is quiet outdated. This is part 1 of the updated hooks version.

Frontend Setup

1. Create project

yarn create react-app hackernews-react-apollo
cd hackernews-react-apollo

2. Add git origin

git add remote origin URL
git add .
git commit -m 'init fresh repo'
git push --set-upstream origin master

3. Restructure app

mkdir src/components src/styles

4. Move App.js into components folder, then move index.css and App.css into styles folder.

5. Update imports.

// index.js
import './styles/index.css';
import App from './components/App';

// App.js
import logo from '../logo.svg';
import '../styles/App.css';

6. Add tacheyons to public/index.html

<!-- public/index.html under other links in head -->
<link rel="stylesheet" href="https://unpkg.com/tachyons@4.2.1/css/tachyons.min.css"/>

7. Replace CSS in index.css

/* index.css */
body {
  margin: 0;
  padding: 0;
  font-family: Verdana, Geneva, sans-serif;
}
input {
  max-width: 500px;
}
.gray {
  color: #828282;
}
.orange {
  background-color: #ff6600;
}
.background-gray {
  background-color: rgb(246,246,239);
}
.f11 {
  font-size: 11px;
}
.w85 {
  width: 85%;
}
.button {
  font-family: monospace;
  font-size: 10pt;
  color: black;
  background-color: buttonface;
  text-align: center;
  padding: 2px 6px 3px;
  border-width: 2px;
  border-style: outset;
  border-color: buttonface;
  cursor: pointer;
  max-width: 250px;
}

8. Add Apollo and GraphQL packages

yarn add @apollo/client graphql

That's it for the setup, we are now ready to start writing some code.

Into the code

index.js

1. Add packages to index.js.

import {
  createHttpLink,
  InMemoryCache,
  ApolloClient,
  ApolloProvider,
} from "@apollo/client";

2. Create variables to connect ApolloClient.

const httpLink = createHttpLink({
  uri: 'http://localhost:4000'
})
const client = new ApolloClient({
  link: httpLink,
  cache: new InMemoryCache()
})

3. Change out wrapper component around <App /> to the Apollo Provider.

  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>,
  document.getElementById('root')

Server

The code to download the backend of the server was not correct on the tutorial. In order to get the correct version, I cloned the React-Apollo Tutorial Repo. Then, I copied the server folder and pasted it into the root of my project. This will add a directory called server to your application. Inside there are prisma files to connect to the database and inside the src folder is the GraphQL server files. We now need to deploy the Prisma database so the GraphQL server can access it.

cd server
yarn install prisma1 global
yarn install
prisma1 deploy

After running prisma1 deploy navigate to Demo server + MySQL database, hit enter and then choose the location closest to you to create your database. Next, we need to run our backend locally. While still in the server directory run yarn start and leave it running. Now we can run two mutations to check our connection to the database. Navigate to http://localhost:4000/ and paste in the following mutations.

mutation CreatePrismaLink {
  post(
    description: "Prisma turns your database into a GraphQL API 😎",
    url: "https://www.prismagraphql.com"
  ) {
    id
  }
}

mutation CreateApolloLink {
  post(
    description: "The best GraphQL client for React",
    url: "https://www.apollographql.com/docs/react/"
  ) {
    id
  }
}

Press the play button and select each mutation once. It should return an id. If this worked, we can verify the links were added by running the following query.

{
  feed {
    links {
      id
      description
      url
    }
  }
}

It should return the json data with the id, description, and url of the 2 links.

Frontend

Now that the backend is working, we can implement the client side of the application. First, we are going to display a list of Link elements. Inside of the components directory, create a file named Link.js and add the following code to it.

import React from 'react'

const Link = (props) => {
  const link = props.link
  return (
    <div>
      {link.description} ({link.url})
    </div>
  )
}

export default Link

This is a React component that is being passed props and then displaying the links from those props. Now we can create the component that will list the links. Add a new file in the components directory called LinkList.js and put the following code inside. For now, we will just hard-code some data do display.

import React from 'react'
import Link from './Link'

const ListLinks = () => {
  const links = [
    {
      id: '1',
      description: 'Prisma turns your database into a GraphQL API 😎',
      url: 'https://www.prismagraphql.com',
    },
    {
      id: '2',
      description: 'The best GraphQL client',
      url: 'https://www.apollographql.com/docs/react/',
    },
  ]
  return (
    <div>
      {links.map(link => <Link key={link.id} link={link} />)}
    </div>
  )
}

export default ListLinks

Now to see the changes, we need to go to App.js and change the contents to the following.

import React from 'react';
import ListLinks from './ListLinks'
import '../styles/App.css';

function App() {
  return (
    <div className="App">
      <ListLinks />
    </div>
  );
}

export default App;

Now if we run yarn start from the root directory, we should see the 2 links displayed on the screen.

GraphQL Query

Next, we'll need to actually query the database for the links stored so they are dynamic instead of hard-coded in. Head to LinkList.js and we are going to change a few things.

1. Import new packages

import gql from 'graphql-tag'
import { useQuery } from '@apollo/client'

2. Underneath the imports add in LINK_QUERY and remove hard-coded links.

// export to be used later and create query for links
export const LINK_QUERY = gql`
{
  feed {
    links {
      id
      url
      description
    }
  }
}
`

3. Destructure off the useQuery hook and update the return statement.

const ListLinks = () => {
  const { loading, error, data } = useQuery(LINK_QUERY)
  return (
    <>
    {/* IF LOADING */}
      {loading && <div>Fetching...</div>}
    {/* IF ERROR */}
      {error && <div>There was an error fetching the data.</div>}
    {/* ELSE RETURN DATA FROM QUERY */}
      {data && (
        <div>{data.feed.links.map(link =>
          <Link key={link.id} link={link} />
        )}
        </div>
      )}
    </>
  )
}

If this worked correctly, we should now have a page that has different states able to be seen on the screen. One while loading, one if there is an error, and the list of links being returned.

Mutations

To add new links to our list we need to add a new file in our components folder called CreateLink.js that includes the following code.

import React, { useState } from 'react'
import { gql, useMutation } from "@apollo/client";

const LINK_MUTATION = gql`
  mutation PostMutation($description: String!, $url: String!) {
    post(description: $description, url: $url) {
      id
      url
      description
    }
  }
`

const CreateLink = () => {
  const [description, setDescription] = useState("")
  const [url, setUrl] = useState("")

  const [createLink] = useMutation(LINK_MUTATION)

  return (
    <div>
      <div className="flex flex-column mt3">
        <input
          className="mb2"
          value={description}
          onChange={e => setDescription(e.target.value)}
          type="text"
          placeholder="A description for the link"
        />
        <input
          className="mb2"
          value={url}
          onChange={e => setUrl(e.target.value)}
          type="text"
          placeholder="The URL for the link"
        />
      </div>
      <button
        onClick={() => {
          createLink({
            variables: {
              description,
              url
            }
          })
        }}
      >
        Submit
        </button>
    </div>
  )
}

export default CreateLink

This file includes the import to use gql and the useMutation hook, the GraphQL mutation, and some state to handle updating the url and description of the link. This can be tested by adding the component into App.js below <ListLinks /> component.

import React from 'react';
import ListLinks from './ListLinks'
import CreateLink from './CreateLink';
import '../styles/App.css';

function App() {
  return (
    <div className="App">
      <ListLinks />
      <CreateLink />
    </div>
  );
}

export default App;

To actually see the update, the page needs to be refreshed or queried in the playground. To avoid this, we can add in React Router to the application to refresh the page.

React Router

Make sure you are in the root directory of the application and run the following command.

yarn add react-router react-router-dom

Now we need to add it to the application in index.js.Import react-router-dom and wrap the ApolloProvider in the router.

import { BrowserRouter as Router } from 'react-router-dom'

ReactDOM.render(
  <Router>
    <ApolloProvider client={client}>
      <App />
    </ApolloProvider>
  </Router>,
  document.getElementById('root')
);

Header

Now, lets create a Header component to hold the links. In the components folder create a new file called Header.js. The following code will import React and the Link component from react-router-dom and display a title and two links.

import React from 'react'
import { Link } from 'react-router-dom'

const Header = () => {
  return (
    <div className="flex pa3 justify-between nowrap orange">
      <div className="fw7 mr1 black">Hacker News</div>
      <div className='flex'>
        <Link to="/" className="ml1 no-underline black">
          new
          </Link>
        <div className="ml1 white">|</div>
        <Link to="/create" className="ml1 no-underline black">
          submit
          </Link>
      </div>
    </div>
  )
}

export default Header

To see the header, we need to add it into App.js. We need to import the Header and the Switch and Route components from react-router-dom.

// add these imports
import { Switch, Route } from 'react-router-dom'
import Header from './Header'

// update App component to the following
function App() {
  return (
    <div className="center w85">
      <Header />
      <div className="ph3 pv1 background-gray">
        <Switch>
          <Route exact path="/" component={ListLinks} />
          <Route exact path="/create" component={CreateLink} />
        </Switch>
      </div>
    </div>
  );
}

Last, we need to update the CreateLink component so the browser will go back to the list after submitting a new link.

// add useHistory import and query to imports
import { LINK_QUERY } from './ListLinks'
import { useHistory } from "react-router-dom";

// initiate useHistory inside component
let history = useHistory();

// update cached links
  const updateCache = (cache, { data }) => {
    const currentLinksList = cache.readQuery({
      query: LINK_QUERY
    })
    const updatedLinksList = [...currentLinksList.feed.links, data.post]

    cache.writeQuery({
      query: LINK_QUERY,
      data: {
        feed: {
          __typename: "Feed",
          links: updatedLinksList,
          count: updatedLinksList.length
        }
      }
    })
  }

// update createLink variable
  const [createLink] = useMutation(LINK_MUTATION, {
    onCompleted: () => history.push("/"),
    onError: () => history.push("/"),
    update: updateCache
  });

Now, the list of links and the create new link are on separate pages. You should have a page that looks similar to this.