Swan Partner Front-end

Onboarding & Banking clients for Swan

• Documentation
• Specifications

Clone

$ git clone git@github.com:swan-io/swan-partner-frontend.git
$ cd swan-partner-frontend

Install

1. Dependencies

Install pnpm (needed for the monorepo management).

$ pnpm install

2. Hosts

Add the following to your /etc/hosts file (so that we're able to replicate the subdomains we'll use in production):

127.0.0.1 banking.swan.local
127.0.0.1 onboarding.swan.local
127.0.0.1 payment.swan.local

3. HTTPS

In order to replicate the production conditions (for session cookies mostly), the local server runs in HTTPS. By default, your system will warn against a self-signed certificate, but we can use mkcert to make the system trust it.

MacOS

With homebrew:

$ brew install mkcert
$ brew install nss # needed for Firefox
$ cd server/keys
$ mkcert -install
$ mkcert "*.swan.local"

Windows

With chocolatey:

$ choco install mkcert
$ cd server/keys
$ mkcert -install
$ mkcert "*.swan.local"

Getting started

To configure your project, simply the following command, it will prompt you with the required values:

$ pnpm configure

and then you start the development server!

$ pnpm dev

Environment variables

If you want to setup your .env file manually:

Server

At the project root, you should find a .env.example file. Copy its contents to a new .env file.

Add your values:

• PARTNER_API_URL
  • https://api.swan.io/sandbox-partner/graphql in sandbox
  • https://api.swan.io/live-partner/graphql in live
• UNAUTHENTICATED_API_URL
  • https://api.swan.io/sandbox-unauthenticated/graphql in sandbox
  • https://api.swan.io/live-unauthenticated/graphql in live
• COOKIE_KEY (generate one using pnpm generate-cookie-key)

And get the following from your dashboard:

• OAUTH_CLIENT_ID: your Swan OAuth2 client ID
• OAUTH_CLIENT_SECRET: your Swan OAuth2 client secret

Don't forget to allow your callback URLs in the dashboard → Developers → API → Redirect URLs, here:

• https://banking.swan.local:8080/auth/callback

Client

You can provide environment variables to the client by adding keys starting with CLIENT_ in your .env file.

Then you can run the following command to make the TypeScript compiler aware of these variables:

$ pnpm type-env-vars

They'll be accessible in the client code in the __env object.

---

Development

To start the development server, use the following command:

$ pnpm dev

You'll find:

• 📁 clients
  • 📁 onboarding: the form for an end user to create a Swan account
  • 📁 banking: the banking interface, including transactions, cards, payments & memberships
• 📁 server: the NodeJS server to handle OAuth2 callbacks & API proxying

Editor

We recommend the following setup for an optimal developer experience:

• VS Code
• VS Code EditorConfig
• VS Code Biome
• VS Code Prettier
• VS Code GraphQL language support and syntax highlighting

By default, the VS Code TypeScript extension only checks the types in open files. If you want your IDE to check types in the whole project, check typescript.tsserver.experimental.enableProjectDiagnostics in your VS Code preferences.

Linting

$ pnpm lint

You can also configure lint-staged as a pre-commit hook by running the following command :

$ pnpm configure-hooks

Ignore code

If you want to ignore a lint rule for a specific line of the code, you can add a suppression comment above the line that emits the lint diagnostic:

// biome-ignore <rule>: <optional-explanation>

For example:

// biome-ignore lint/suspicious/noNamespace:
namespace foo {}

For useExhaustiveDependencies (equivalent of react-hooks/exhaustive-deps), you can even specify which dependencies are ignored, on multiple lines:

// biome-ignore lint/correctness/useExhaustiveDependencies(fn):
// biome-ignore lint/correctness/useExhaustiveDependencies(value):
useEffect(fn, [fn, value]);

Testing

$ pnpm test

We generally collocate test files next to their implementation, in a __tests__ directory, with the tested file name suffixed with .test:

> utils
  > __tests__
    > myFile.test.tsx
  > myFile.tsx

We use Vitest and React Testing Library.