Userfront Toolkit

Development

See the root README.md in the root of this repo for full dev setup instructions.

To install and run this package only for development, in this folder:

Install dependencies: npm install
Run unit tests: npm test
Run unit tests in watch mode: npm run watch
Run Storybook: npm run storybook and see output for local server URL

Architecture

This project uses Vite to build the bundle, using Vite's build-in support for TypeScript.

Some parts of the project are in TypeScript .ts/.tsx and other parts are in JavaScript .js/.jsx. TypeScript is used where its features are particularly beneficial, mostly in the models that describe forms' behavior.

There are two entry points.

One exports the forms as React components:

import Userfront, { LoginForm } from "@userfront/toolkit/react";

The other registers the forms as Web Components, suitable for usage with most front-end frameworks or in plain JS:

import Userfront from "@userfront/toolkit/web-components";

After import, the Web Components are registered and can be used anywhere in the app:

<body>
  <login-form tenant-id="mytenantid"></login-form>
</body>

Testing

Vitest is used for unit tests. Its interface is similar to Jest, with a few additional features.

There is a useful VS Code extension for Vitest to run tests and view results directly in the editor.

High-level structure

The signup and login forms are split into models and views.

Each "screen" on the form is a view. These are (mostly) stateless React components that emit events on user actions and receive a context with current state and data. The intent is that, for ease of testing and maintenance, each form is a simple function of data to UI. Every form state can be accessed by passing an appropriate context to the form component.

Each view has a model, which is an XState statechart describing how the form changes over time as events happen. There is a VS Code plugin for XState that allows visualizing and editing statecharts directly in the editor. Editing statecharts with this extension is not recommended because it tends to make unwanted changes, but it's useful for visualizing statecharts to understand the model's behavior.

The models use TypeScript for added robustness via static typing.

The signup and login forms also have models, which incorporate the models for each view.

The logout button, password reset request form, and password reset form are simple enough that they don't use XState models and aren't split into views.

The src directory contains the package's source:

src/assets - static assets
src/themes - CSS files
src/components - basic components for the forms: buttons, inputs, etc.
src/views - views for the signup and login forms
src/models - each view, and the login and signup form, has an XState model in this folder
src/forms - the "plain" forms, without models. The login and signup forms here are more for test usage.
src/packaged-forms - the "packaged" login and signup forms, connected to appropriate models, for client usage.
src/services - internal tools
src/utils - internal tools
src/stories - Storybook stories.

CSS

The forms' CSS is in themes/dynamic.css. This uses CSS variables to allow full customization of forms' appearance. Variables are all prefixed --userfront to separate them from variables in client code. The dynamic theme uses CSS's color modification capabilities (color-mix mostly) to derive a full color scheme (with active/hover states etc) from 1-3 main colors: "dark" (primary), "light" (secondary), and "accent".

Storybook

The components and views can all be inspected with Storybook. There is a custom-built system to declare and inject CSS variables into components in Storybook and allow modifying them with knobs.