The Stack Part 3: Building a Frontend

In the last post we set up our deployment, fully automated on merge to our main branch. In this post we will be building our UI (Frontend) applications. See the full overview of posts here.

At the end of this post we will have:

• A Next.js Frontend app with support for localization, using Tailwind CSS.
• A Leptos Rust/WASM Frontend app with support for localization, using Tailwind CSS.
• Automatic deployment of our Apps AWS using CDK, statically hosted using S3 + CloudFront.

We are essentially hedging our bets by building both a JavaScript-based Frontend, which is the safe bet, and a Rust/WASM-based Frontend, which is the future bet. We will be using the same GraphQL API for both, so we can easily switch between them.

There is quite a lot to cover. My recommendation is to clone down the Part 3 branch in the GitHub repository and use this post as an explanation of what is set up.

Prelude: Static Site Generation

While SSR (Server Side Rendering) is seeing a renaissance these days, we are intentionally avoiding this functionality. If you remember the architecture outlined in our introduction to the series, we want to be able to serve our Frontend entirely using static file hosting.

There are multiple reasons for this, going back to our core design goals:

• Low cost: Static file hosting is extremely cheap, and scales as well as S3/CloudFront does (i.e. very well).
• Low operational overhead: Static file hosting is extremely simple to operate—there are no servers for us to worry about and scale up/down as needed, no need for any orchestration yet.
• Performant: Static file hosting is extremely performant, as the files are served directly from the edge, and not from a server.

We do sacrifice the ability to do SSR and the various User Experiences that can potentially bring, but the benefits are far outweighed by the downsides in this tradeoff.

Next.js

Next.js is one of the most popular React frameworks at the moment, and supports a lot of niceties as well as sets us on a path of a good structure from the get-go. It has a lot of momentum behind it, a strong focus on the Developer Experience, and uses React which makes it a very familiar option for a large majority of Frontend Engineers out there.

We'll once again use Bun, which you can install via:

$ curl -fsSL https://bun.sh/install | bash

While bun unfortunately doesn't fully support the Next.js App Router yet we will still rely on it for installing dependencies and being our general go-to tool for running anything JS related.

Setting up our Next.js App

Let's get our Next.js app set up, which we will call ui-app:

$ bun create next-app # Call it ui-app
✔ What is your project named? … ui-app
✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to customize the default import alias (@/*)? … No

This gets us quite far, we now have an App we can run, Tailwind CSS is already set up, and we got a lot of the structure set up for us:

$ cd ui-app
$ bun run dev # or bun run build
next dev
  ▲ Next.js 13.5.4
  - Local:        http://localhost:3000

 ✓ Ready in 3s

Voila, we've got a little Hello World Next.js app!

Building Static Files

We need to do just one small change to our Next.js setup to make it output static files for us. We'll do this by adding output: "export" to our next.config.js file at the root of ui-app/:

1
// @ts-check
2

3
/** @type {import('next').NextConfig} */
4
const nextConfig = {
5
  output: "export",
6
  trailingSlash: true,
7
  experimental: {
8
    // Statically type links to prevent typos and other errors when using next/link, improving type safety when navigating between pages.
9
    typedRoutes: true,
10
  },
11
};
12

13
module.exports = nextConfig;

We also enabled trailingSlash (docs here) to make Next.js work nicely with CloudFront.

This tells Next.js that we want to to Statically Export our files, which will generate an HTML file per route, which allows each route to serve the minimal content it needs, enabling faster page loads, instead of the traditional SPA approach of serving one large file upfront.

We get the best of both worlds here, as we still get the reduced bundle sizes typical of SSR, but can retain the static file advantage of SPAs.

Setting up Localization

As our customer-base grows, we will inevitably run into the need to localization. To do this, we will restructure our App with basic support for this, as well as bring in a dependency to help us with this, namely next-intl. Vercel also has some good documentation on how to Get Started here.

Let's start by adding the dependency:

$ bun add next-intl

We'll also create a folder that will contain our localization files, which we'll call messages/ in the root of the ui-app/ project:

$ mkdir messages

This allows us to set up some text for our first languages. Create an English locale, messages/en.json, with the following:

1
{
2
  "home": {
3
    "intro": "Welcome!"
4
  }
5
}

And also a French locale, in messages/fr.json:

1
{
2
  "home": {
3
    "intro": "Bienvenue!"
4
  }
5
}

To make this a bit nicer to work with, we'll also add typesafety by letting TypeScript know what keys we support in our localization function. Create a ui-app/global.d.ts file with the following:

1
// Use type safe message keys with `next-intl`, based on the contents/keys of
2
// our default english locale.
3
type Messages = typeof import("./messages/en.json");
4
declare interface IntlMessages extends Messages {}

This ensures that if we misspell a key, or even remove one later on, we will be highlighted of the incorrect usage by TypeScript.

We can now set up a route using the App Router to pick up our locale. We'll want the locale to be part of our URL as a prefix on all routes, so that we can pick it up as a dynamic segment and use it to load the correct localization file.

First we will create a folder where our localized pages will live in, and also clean up the default files that Next.js created for us:

$ mkdir "src/app/[locale]"
$ rm src/app/page.tsx src/app/layout.tsx

Let's create a simply page in here at src/app/[locale]/page.tsx, and get our welcome text from the localization file:

1
"use client";
2

3
import { useTranslations } from "next-intl";
4

5
export default function Home() {
6
  const t = useTranslations("home");
7

8
  return (
9
    // Name="grid place-content-center content-center h-screen">
10
    <div class,linenos
11
    // Name="text-6xl">{t("intro")}</h1>
12
      <h1 class,linenos
13
      // Name="grid gap-4 grid-cols-2">
14
      <div class,linenos
15
        <a href="/fr">Go to fr</a>
16
        <a href="/en">Go to en</a>
17
      </div>
18
    </div>
19
  );
20
}

We'll need to mark the component as 'use client' for now, while next-intl is working on server-side support.

Since we removed existing layout file, we need to define a new one that also handles setting up our localization at the root of our components. We'll create a src/app/[locale]/layout.tsx file with the following:

1
import "../globals.css";
2
import type { Metadata } from "next";
3
import { Inter } from "next/font/google";
4
import { NextIntlClientProvider } from "next-intl";
5
import { notFound } from "next/navigation";
6
import { ReactNode } from 'react';
7
import { promises as fs } from 'fs';
8

9
export const metadata: Metadata = {
10
  title: "Hello, World!",
11
  description: "Ready to set things up",
12
}
13

14
const inter = Inter({ subsets: ["latin"] });
15

16
/**
17
 * Set up all supported locales as static parameters, which ensures we generate
18
 * static pages for each possible value of `locale`.
19
 */
20
export async function generateStaticParams() {
21
  // Construct an array of all supported locales based on the files in the `messages/` directory.
22
  const localeFiles = await fs.readdir(`${process.cwd()}/messages`);
23
  return localeFiles.map((f) => ({locale: f.replace(/\.json$/, "")}));
24
}
25

26
/**
27
 * Load the contents of a given locale's messages file.
28
 */
29
async function messagesContent(locale: string) {
30
  try {
31
    return (await import(`../../../messages/${locale}.json`)).default;
32
  } catch (error) {
33
    console.error("Something went wrong", error);
34
    notFound();
35
  }
36
}
37

38
type Props = {
39
  children: ReactNode;
40
  params: {
41
    locale: string;
42
  };
43
};
44

45
export default async function Layout({ children, params: { locale } }: Props) {
46
  const messages = await messagesContent(locale);
47
  return (
48
    <html lang={locale}>
49
    // Name={inter.className}>
50
      <body class,linenos
51
        <NextIntlClientProvider locale={locale} messages={messages}>
52
          {children}
53
        </NextIntlClientProvider>
54
      </body>
55
    </html>
56
  );
57
}

To avoid needing to maintain a hardcoded list of locales, we dynamically find all the locales defined in our messages/ folder during build time, and construct a list of supported locales from this. We then pass the contents of this into NextIntlClientProvider.

We could imagine later on, once our translation file becomes massive, that we split up en.json into smaller segments such as en/home.json, and load these parts specifically in a app/[locale]/home/layout.tsx file. For now though, we'll keep it simple.

As the final piece of this puzzle, we need a way to let Next.js know where it should route to by default, since we removed the default root pages.

We unfortunately cannot use middlewares when statically exporting our site, so we will instead redirect the user upon loading the page. Create a src/app/page.tsx file with the following:

1
import { redirect } from "next/navigation";
2

3
export default function Root() {
4
  redirect("/en");
5
}

Along with a root layout file at src/app/layout.tsx:

import { ReactNode } from "react";

type Props = {
  children: ReactNode;
};

export default function Layout({ children }: Props) {
  return children;
}

You should now have a structure that looks like this:

.
├── README.md
├── bun.lockb
├── global.d.ts
├── messages
│   └── en.json
│   └── fr.json
├── next.config.js
├── package.json
├── postcss.config.js
├── public
│   └── favicon.ico
├── src
│   └── app
│       ├── [locale]
│       │   ├── layout.tsx
│       │   └── page.tsx
│       ├── favicon.ico
│       ├── globals.css
│       ├── layout.tsx
│       └── page.tsx
├── tailwind.config.ts
└── tsconfig.json

And that's it! We're now able to run our app and check it out in the browser:

$ bun run dev

Screenshot of our ui-app

It may not look like much, but we've implemented a lot of the core functionality we need to get started, such as static builds and localization.

As the final step we will add our commands to just, extending our existing justfile:

1
_setup-ui-app:
2
  #!/usr/bin/env bash
3
  set -euxo pipefail
4
  cd ui-app
5
  bun install

We'll also set up a new command for running our development server:

1
# Run <project> development server, e.g. `just dev ui-app`.
2
dev project:
3
  just _dev-{{project}}
4

5
_dev-ui-app:
6
  #!/usr/bin/env bash
7
  set -euxo pipefail
8
  cd ui-app
9
  bun dev

Leptos (Rust/WASM)

Leptos is one of the newer entries on the Rust/WASM scene. It has a radical focus on performance and scalability of your codebase, so that as your codebase grows your App doesn't just start to become slower which is a typical issue in React and VDOM-based frameworks.

Leptos should feel somewhat familiar, although it is more closely related to something like Solid.js which is based on Signals and not using a VDOM. Leptos has a good quick overview of features here and a nice FAQ here.

Setting up our Leptos App

We will be using Trunk for developing and building our Leptos App. Trunk is a great tool for developing Rust/WASM Apps, and is very similar to Bun (in a sense) in that it is a wrapper around the underlying tools. Let's install it first:

# Install dependencies
$ cargo install trunk

We can then set up our project, which we'll call ui-internal:

$ cargo init ui-internal
$ cd ui-internal

We'll immediately adjust our Cargo.toml file with the dependencies we'll need, as well as a few common WASM optimizations for our release builds:

1
[package]
2
name = "ui-internal"
3
version = "0.1.0"
4
edition = "2021"
5

6
# Define our supported locales.
7
[package.metadata.leptos-i18n]
8
default = "en"
9
locales = ["en"]
10
locales-dir = "./messages"
11

12
# Optimize for WASM binary size.
13
[profile.release]
14
opt-level = 'z'
15
lto = true
16
codegen-units = 1
17

18
[dependencies]
19
# Core leptos library.
20
leptos = { version = "0.5.1", features = ["csr", "nightly"] }
21
# Leptos Meta adds support for adjusting <head> from within components.
22
leptos_meta = { version = "0.5.1", features = ["csr", "nightly"] }
23
# Router and Route state management.
24
leptos_router = { version = "0.5.1", features = ["csr", "nightly"] }
25
# Leptos support for i18n localization.
26
leptos_i18n = { version = "0.2", features = ["csr", "nightly"] }
27
# Lightweight logging support.
28
log = "0.4"
29

30
# Common WASM libraries.
31
wasm-bindgen = { version = "0.2" }
32
console_log = { version = "1" }
33
console_error_panic_hook = { version = "0.1" }

And finally, we'll use Rust Nightly to develop our App, which gives us a few better ergonomics:

$ rustup toolchain install nightly
$ rustup default nightly
$ rustup target add wasm32-unknown-unknown

Let's create a quick index.html file in the root of the ui-internal/ folder, just to get started:

1
<!DOCTYPE html>
2
<html>
3
  <head></head>
4
  <body></body>
5
</html>

And replace the contents of our src/main.rs:

1
use leptos::*;
2

3
mod app;
4

5
pub fn main() {
6
    // Register log and panich handlers.
7
    let _ = console_log::init_with_level(log::Level::Debug);
8
    console_error_panic_hook::set_once();
9

10
    mount_to_body(|| {
11
        view! { <app::Layout /> }
12
    });
13
}

We'll also create a src/app.rs file with the following (we'll update this file later):

1
use leptos::*;
2

3
#[component]
4
pub fn Layout() -> impl IntoView {
5
    view! { <p>"Hello, world!"</p>}
6
}

We can now run our App using Trunk:

$ trunk serve --open

Voila, we've got a little Hello World Leptos app!

Setting up Tailwind CSS

Let's configure Tailwind CSS for our Leptos App. First, we need to tell Tailwind where to look for files that might contain our CSS classes. Create a ui-internal/tailwind.config.ts file with the following:

1
/** @type {import('tailwindcss').Config} */
2
module.exports = {
3
  content: {
4
    files: ["*.html", "./src/**/*.rs"],
5
  },
6
  theme: {
7
    extend: {},
8
  },
9
  plugins: [],
10
};

We also need to tell trunk to build Tailwind CSS as part of its build process. We can do this by creating a ui-internal/Trunk.toml file:

1
[[hooks]]
2
stage = "pre_build"
3
command = "sh"
4
command_arguments = [
5
  "-c",
6
  "bunx tailwindcss --input resources/input.css --output public/output.css",
7
]

This let's trunk know that before it builds our WASM App, it should run the bunx tailwindcss ... command, which will generate our Tailwind CSS file, which it puts into public/output.css.

Now, you might have noticed we also have an input file. Let's get that set up, along with a resources/ folder:

$ mkdir ui-internal/resources

We'll then create our base Tailwind CSS file at ui-internal/resources/input.css, mimicing our Next.js setup:

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;
4

5
:root {
6
  --foreground-rgb: 0, 0, 0;
7
  --background-start-rgb: 214, 219, 220;
8
  --background-end-rgb: 255, 255, 255;
9
}
10

11
@media (prefers-color-scheme: dark) {
12
  :root {
13
    --foreground-rgb: 255, 255, 255;
14
    --background-start-rgb: 0, 0, 0;
15
    --background-end-rgb: 0, 0, 0;
16
  }
17
}
18

19
body {
20
  color: rgb(var(--foreground-rgb));
21
  background: linear-gradient(
22
      to bottom,
23
      transparent,
24
      rgb(var(--background-end-rgb))
25
    )
26
    rgb(var(--background-start-rgb));
27
}
28

Final step, we need to pull in our Tailwind CSS file in our index.html. Update the contents to the following:

1
<!DOCTYPE html>
2
<html lang="en">
3
  <head>
4
    <meta charset="utf-8" />
5
    <link data-trunk rel="rust" data-wasm-opt="z" />
6
    <link data-trunk rel="icon" type="image/ico" href="/public/favicon.ico" />
7
    <link data-trunk rel="css" href="/public/output.css" />
8
    <title>Hello, World!</title>
9
  </head>
10

11
  <body></body>
12
</html>

And that's it! We've now integrated Tailwind CSS into our Leptos App.

Setting up Localization

We're using leptos_i18n for localization in Leptos, which supports an API that's very close to the one we used in Next.js. We already pulled in the dependency when we updated our Cargo.toml file earlier, so let's get the rest of it set up.

We'll create a ui-internal/messages/ folder where our locales will live:

$ mkdir ui-internal/messages

We'll define our first locale, English, in a messages/en.json file:

1
{
2
  "home": {
3
    "intro": "Welcome!"
4
  }
5
}

And also a French locale, in a messages/fr.json file:

1
{
2
  "home": {
3
    "intro": "Bienvenue!"
4
  }
5
}

leptos_i18n exposes a macro load_locales!() that looks for our configuration and generates code specific for our project that we can load in our App.

Let's update src/main.rs, and also pull in a new module home in anticipation of creating splitting our code out from the current app.rs file:

1
use leptos::*;
2

3
mod app;
4
mod home;
5

6
// Load our locales from the files defined in `Cargo.toml`.
7
leptos_i18n::load_locales!();
8

9
pub fn main() {
10
    // Register log and panich handlers.
11
    let _ = console_log::init_with_level(log::Level::Debug);
12
    console_error_panic_hook::set_once();
13

14
    mount_to_body(|| {
15
        view! { <app::Layout /> }
16
    });
17
}

Let's create a src/home.rs in which will use our locales:

1
use crate::i18n::*;
2
use leptos::*;
3
use leptos_router::*;
4

5
#[component]
6
pub fn Page() -> impl IntoView {
7
    let i18n = use_i18n();
8

9
    view! {
10
        <div class="grid place-content-center content-center h-screen">
11
            <h1 class="text-6xl">{t!(i18n, home.intro)}</h1>
12
            <div class="grid gap-4 grid-cols-2">
13
                <A href="/fr">"Go to fr"</A>
14
                <A href="/en">"Go to en"</A>
15
            </div>
16
        </div>
17
    }
18
}

The magic here comes from the crate::i18n::* which got generated by leptos_i18n::load_locales!(), and the use_i18n hook that we now got access to. Very similar to our Next.js App, we then call the macro t! to get the correct translation for the current locale, given a JSON key.

We're not entirely done yet, we need to tell our Leptos App about the I18nContext at the root of our application. We also still need to add support for routing between locales.

Let's update src/app.rs to do this:

1
use crate::i18n::*;
2
use leptos::*;
3
use leptos_meta::*;
4
use leptos_router::*;
5

6
use crate::home;
7

8
const DEFAULT_LOCALE: &str = "en";
9

10
#[derive(Params, PartialEq, Clone, Debug)]
11
pub struct LayoutParams {
12
    locale: String,
13
}
14

15
#[component(transparent)]
16
fn LocalizedRoute<P, F, IV>(path: P, view: F) -> impl IntoView
17
where
18
    P: std::fmt::Display,
19
    F: Fn() -> IV + 'static,
20
    IV: IntoView,
21
{
22
    view! {
23
        <Route path=format!("/:locale{}", path) view=move || {
24
            // Extract the locale from the path.
25
            let i18n = use_i18n();
26
            let params = use_params::<LayoutParams>();
27
            let chosen_locale = move || params().map(|params| params.locale).unwrap_or(DEFAULT_LOCALE.to_string());
28

29
            create_effect(move |_| {
30
                // Figure out what the current locale is, and if it matches the chosen locale from path.
31
                let current_locale = i18n();
32
                let new_locale = match chosen_locale().as_str() {
33
                    "fr" => Locale::fr,
34
                    "en" => Locale::en,
35
                    _ => Locale::en,
36
                };
37
                // Update the locale if necessary.
38
                if current_locale != new_locale {
39
                    i18n(new_locale);
40
                }
41
            });
42

43
            view! {
44
                {view()}
45
            }
46
        }/>
47
    }
48
}
49

50
#[component]
51
pub fn Layout() -> impl IntoView {
52
    provide_meta_context();
53
    provide_i18n_context();
54

55
    view! {
56
        <Router>
57
            <main>
58
                <Routes>
59
                    <Route path="" view=move || view! { <Redirect path=format!("/{}", DEFAULT_LOCALE)/> }/>
60
                    <LocalizedRoute path="" view=move || view! { <home::Page/> }/>
61
                </Routes>
62
            </main>
63
        </Router>
64
    }
65
}

There's a lot to unpack here, so let's go through it step by step.

• In our pub fn Layout() -> impl IntoView component we set up a normal Router component, which will handle routing for us.
• We introduce a special route, LocalizedRoute, which handles detecting our locale and switching the active locale if the path changes.
• In our fn LocalizedRoute function we wrap the normal Route component, and inject a bit of logic before returning the view that was otherwise passed into our LocalizedRoute.

The last part is the most interesting, so let's break down what we are doing inside the Route we are setting up for LocalizedRoute.

First we get the current parameters, which we know will contain a locale key:

1
// Extract the locale from the path.
2
let i18n = use_i18n();
3
let params = use_params::<LayoutParams>();
4
let chosen_locale = move || params().map(|params| params.locale).unwrap_or(DEFAULT_LOCALE.to_string());

We then create an effect that will run every time the parameters change, which will be every time the path changes:

1
create_effect(move |_| {
2
    // Figure out what the current locale is, and if it matches the chosen locale from path.
3
    let current_locale = i18n();
4
    let new_locale = match chosen_locale().as_str() {
5
        "fr" => Locale::fr,
6
        "en" => Locale::en,
7
        _ => Locale::en,
8
    };
9
    // Update the locale if necessary.
10
    if current_locale != new_locale {
11
        i18n(new_locale);
12
    }
13
});

The thing that makes our effect rerun is our usage of i18n() which subscribes us to the signal, and thus reruns the effect every time the locale changes.

You should now have a structure that looks like this:

.
├── Cargo.lock
├── Cargo.toml
├── Trunk.toml
├── index.html
├── messages
│   ├── en.json
│   └── fr.json
├── public
│   └── favicon.ico
├── resources
│   └── input.css
├── src
│   ├── app.rs
│   ├── home.rs
│   └── main.rs
├── tailwind.config.ts

And that's it! We're now able to run our app and check it out in the browser:

$ trunk serve --open

Screenshot of our ui-internal

Again, it may not look like much, but we've implemented a lot of the core functionality we need to get started!

As the final step we will add our commands to just, extending our existing justfile:

1
_setup-ui-internal:
2
  #!/usr/bin/env bash
3
  set -euxo pipefail
4
  cd ui-internal
5
  rustup toolchain install nightly
6
  rustup default nightly
7
  rustup target add wasm32-unknown-unknown
8

9
_dev-ui-internal:
10
  #!/usr/bin/env bash
11
  set -euxo pipefail
12
  cd ui-internal
13
  trunk serve

Bonus: End-to-End Tests

End-to-End tests are a great way to ensure that our App is working as expected, and that we don't accidentally break something when we make changes. We'll use Playwright for this, which is a great tool for writing End-to-End tests.

We want three different test suites to cover:

• ui-app: Test our Next.js App.
• ui-internal: Test our Leptos App.
• deployment.: Test our deployed App to verify it is working as expected.

Let's start by setting up our folder structure. Many of our configuration files will be the same across all three test suites, let's create an end2end folder for our projects:

$ mkdir -p deployment/end2end/tests
$ mkdir -p ui-app/end2end/tests
$ mkdir -p ui-internal/end2end/tests

We intentionally make a distinction between end2end/ and unit/integration tests which will live in tests/. These have very different requirements for how to run them, and we often want to run them at different times.

Before we can run anything, we will need a couple of other files to set up Playwright as well as support for TypeScript.

Let's create a tsconfig.json for all for all three projects (ui-app, ui-internal, and deployment). We'll place it at <project>/end2end/tsconfig.json:

1
{
2
  "compilerOptions": {
3
    "lib": ["esnext"],
4
    "module": "esnext",
5
    "target": "esnext",
6
    "moduleResolution": "bundler",
7
    "noEmit": true,
8
    "allowImportingTsExtensions": true,
9
    "moduleDetection": "force",
10
    "allowJs": true, // allow importing `.js` from `.ts`
11
    "esModuleInterop": true, // allow default imports for CommonJS modules
12
    "strict": true,
13
    "forceConsistentCasingInFileNames": true,
14
    "skipLibCheck": true,
15
    "noImplicitAny": false
16
  }
17
}

Now, let's configure Playwright for all for all three projects (ui-app, ui-internal, and deployment). We'll place it at <project>/end2end/playwright.config.ts:

1
import type { PlaywrightTestConfig } from "@playwright/test";
2
import { devices } from "@playwright/test";
3

4
const SERVER = `http://localhost:8080`;
5

6
const config: PlaywrightTestConfig = {
7
  testDir: "./tests",
8
  // Maximum time one test can run for.
9
  timeout: 30 * 1000,
10
  expect: {
11
    /**
12
     * Maximum time expect() should wait for the condition to be met.
13
     * For example in `await expect(locator).toHaveText();`
14
     */
15
    timeout: 5000,
16
  },
17
  // Run tests in files in parallel.
18
  fullyParallel: true,
19
  // Fail the build on CI if you accidentally left test.only in the source code.
20
  forbidOnly: !!process.env.CI,
21
  // Retry on CI only.
22
  retries: process.env.CI ? 2 : 0,
23
  // [Optional] Opt out of parallel tests on CI.
24
  // workers: process.env.CI ? 1 : undefined,
25
  // Limit the number of failures on CI to save resources
26
  maxFailures: process.env.CI ? 10 : undefined,
27

28
  reporter: "html",
29
  use: {
30
    // Base URL to use in actions like `await page.goto('/')`.
31
    baseURL: SERVER,
32
    // Maximum time each action such as `click()` can take. Defaults to 0 (no limit).
33
    actionTimeout: 0,
34
    // Collect trace when retrying the failed test.
35
    trace: "on-first-retry",
36
  },
37

38
  // Configure which browsers to test against.
39
  projects: [
40
    {
41
      name: "chromium",
42
      use: {
43
        ...devices["Desktop Chrome"],
44
      },
45
    },
46
  ],
47
  webServer: {
48
    command: "just dev ui-internal",
49
    url: SERVER,
50
    reuseExistingServer: true,
51
    stdout: "ignore",
52
    stderr: "pipe",
53
  },
54
};
55

56
export default config;

There are some minor adjustments we want to do in the above configuration for each project:

• ui-app: Set the SERVER variable to http://localhost:3000 and command to just dev ui-app.
• ui-internal: Set the SERVER variable to http://localhost:8080 and command to just dev ui-internal.
• deployment: Remove the webServer block, and set the SERVER variable to http://${process.env.DOMAIN}.

And a package.json in <project>/end2end/package.json:

1
{
2
  "name": "end2end",
3
  "version": "1.0.0",
4
  "description": "",
5
  "main": "index.js",
6
  "scripts": {
7
    "setup": "playwright install",
8
    "e2e": "playwright test"
9
  },
10
  "keywords": [],
11
  "author": "",
12
  "license": "ISC",
13
  "devDependencies": {
14
    "bun-types": "latest",
15
    "@types/node": "^20.5.0",
16
    "typescript": "^5",
17
    "@playwright/test": "^1.38.1"
18
  }
19
}

We are now ready to add our first test! Since we have just added localization, let's make sure that it works and doesn't regress.

For all three projects ui-app, deployment, and ui-internal we'll create a test in <project>/end2end/tests/localization.spec.ts:

1
import { test, expect } from "@playwright/test";
2

3
test("localization translates text when changing language", async ({ page }) => {
4
  await page.goto("/");
5
  await expect(page.locator("h1")).toHaveText(
6
    "Welcome!"
7
  );
8

9
  await page.getByText('Go to fr').dblclick();
10
  await expect(page.locator("h1")).toHaveText(
11
    "Bienvenue!"
12
  );
13
});
14

15
test("localization loads correct text from URL", async ({ page }) => {
16
  await page.goto("/fr");
17
  await expect(page.locator("h1")).toHaveText(
18
    "Bienvenue!"
19
  );
20
});

This same test works for both apps since we've set them up with the same functionality.

Let's try and run them:

$ cd ui-app/end2end # or cd ui-internal/end2end
$ bun run e2e

And for deployment we can test it locally by starting up just dev ui-app in another terminal, and then running:

$ cd deployment/end2end # or cd ui-internal/end2end
$ DOMAIN="localhost:3000" bun run e2e

NOTE: You might want to add the following to your .gitignore:

1
playwright-report
2
test-results

And that's it! We've now got an easy way to run End-to-End tests. Let's do our final step and add this to our justfile:

1
# Run End-to-End tests for <project>, e.g. `just e2e ui-internal`.
2
e2e project:
3
  just _e2e-{{project}}
4

5
_e2e-deployment:
6
  cd deployment/end2end && bun run e2e
7

8
_e2e-ui-app:
9
  cd ui-app/end2end && bun run e2e
10

11
_e2e-ui-internal:
12
  cd ui-internal/end2end && bun run e2e

And we'll also update our _setup-project commands to setup the Playwright dependencies:

1
_setup-deployment:
2
  #!/usr/bin/env bash
3
  set -euxo pipefail
4
  cd deployment
5
  bun install
6
  cd end2end
7
  bun install
8
  bun run setup
9

10
_setup-ui-app:
11
  #!/usr/bin/env bash
12
  set -euxo pipefail
13
  cd ui-app
14
  bun install
15
  cd end2end
16
  bun install
17
  bun run setup
18

19
_setup-ui-internal:
20
  #!/usr/bin/env bash
21
  set -euxo pipefail
22
  cd ui-internal
23
  rustup toolchain install nightly
24
  rustup default nightly
25
  rustup target add wasm32-unknown-unknown
26
  cd end2end
27
  bun install
28
  bun run setup

Bonus: DevEx Improvements

There are a few Editor improvements that are recommended for working with Leptos and Tailwind CSS if you are using VS Code.

Add to your settings:

1
{
2
  "rust-analyzer.procMacro.ignored": {
3
    "leptos_macro": ["server", "component"]
4
  },
5
  "emmet.includeLanguages": {
6
    "rust": "html",
7
    "*.rs": "html"
8
  },
9
  "tailwindCSS.includeLanguages": {
10
    "rust": "html",
11
    "*.rs": "html"
12
  },
13
  "files.associations": {
14
    "*.rs": "rust"
15
  },
16
  "editor.quickSuggestions": {
17
    "other": "on",
18
    "comments": "on",
19
    "strings": true
20
  },
21
  "css.validate": false
22
}

Another nice tool is leptosfmt, which helps keep our Leptos View macro code nicely formatted.

You can install it via:

$ cargo install leptosfmt

And then add this to your settings:

1
{
2
  "rust-analyzer.rustfmt.overrideCommand": ["leptosfmt", "--stdin", "--rustfmt"]
3
}

Automating Deployments via CDK

Since we are now generating artifacts that we want to deploy, from multiple projects, we need to restructure our existing deployment pipeline slightly.

We still want to retain staggered deployments, but we need a bit of coordination to make sure we have all relevant artifacts before we deploy.

Our new flow will look like this:

Updated deployment pipeline

Building artifacts in CI

In this part we will be doing the following:

• Extend our existing cd-deploy.yml workflow to build artifacts for ui-app and ui-internal via a reuseable workflow.
• Extend our existing wf-deploy.yml workflow to download artifacts so it can use it during deployments.
• Set up a reuseable workflow, wf-build.yml, that will build our artifacts.
• Set up a reuseable workflows for both ui-app and ui-internal that will do the actual building.

Let's start with our wf-build-ui-app.yml workflow:

1
name: "Build: ui-app"
2

3
on:
4
  workflow_call:
5
    inputs:
6
      release:
7
        type: boolean
8
        default: false
9
      upload-artifact:
10
        type: boolean
11
        default: false
12

13
jobs:
14
  ui-app:
15
    runs-on: ubuntu-latest
16
    steps:
17
      - uses: actions/checkout@v3
18
      - uses: actions/setup-node@v3
19
        with:
20
          node-version: 20
21
      - uses: oven-sh/setup-bun@v1
22
      - uses: extractions/setup-just@v1
23

24
      - name: Install dependencies
25
        working-directory: ./ui-app
26
        run: bun install
27

28
      - name: Build Next.js project
29
        run: just build ui-app
30

31
      - uses: actions/upload-artifact@v3
32
        if: ${{ inputs.upload-artifact }}
33
        with:
34
          name: ui-app
35
          path: ui-app/out
36
          if-no-files-found: error
37
          retention-days: 1

And our wf-build-ui-internal.yml workflow:

1
name: "Build: ui-internal"
2

3
on:
4
  workflow_call:
5
    inputs:
6
      release:
7
        type: boolean
8
        default: false
9
      upload-artifact:
10
        type: boolean
11
        default: false
12

13
jobs:
14
  ui-internal:
15
    runs-on: ubuntu-latest
16
    steps:
17
      - uses: actions/checkout@v3
18
      - uses: oven-sh/setup-bun@v1
19
      - uses: extractions/setup-just@v1
20
      - name: Install Rust toolchain
21
        uses: dtolnay/rust-toolchain@nightly
22
        with:
23
          toolchain: nightly-2023-10-11
24
          targets: wasm32-unknown-unknown
25

26
      - name: Install trunk
27
        uses: jaxxstorm/[email protected]
28
        with:
29
          repo: thedodd/trunk
30
          platform: linux # Other valid options: 'windows' or 'darwin'.
31
          arch: x86_64
32

33
      - uses: actions/cache@v3
34
        continue-on-error: false
35
        with:
36
          path: |
37
            ~/.cargo/registry
38
            ~/.cargo/git
39
            ui-internal/target
40
          key: cargo-${{ hashFiles('Cargo.lock') }}-${{ hashFiles('ui-internal/Cargo.lock') }}-ui-internal
41
          restore-keys: cargo-
42

43
      - name: Build release build
44
        if: ${{ inputs.release }}
45
        run: just build ui-internal
46

47
      - name: Build debug build
48
        if: ${{ !inputs.release }}
49
        run: just build ui-internal true
50

51
      - uses: actions/upload-artifact@v3
52
        if: ${{ inputs.upload-artifact }}
53
        with:
54
          name: ui-internal
55
          path: ui-internal/dist
56
          if-no-files-found: error
57
          retention-days: 1