@therjfelix/userfront-react v1.0.0-alpha.15

Userfront Toolkit - React

Toolkit installation and usage

Install: npm install --save @userfront/react

Use:

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

Userfront.init("myTenantId");

export default function MyComponent() {
  return <SignupForm />;
}

or

// App.js
import { UserfrontContext } from "@userfront/react"

export default function App() {
  return (
    <UserfrontContext tenantId="myTenantId">
      <Component>
    </UserfrontContext>
  )
}

// MyComponent.js
import { SignupForm } from "@userfront/react";

export default function MyComponent() {
  return <SignupForm />;
}

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:

1. Install dependencies: npm install

2. Run unit tests: npm test

3. Run unit tests in watch mode: npm run watch

4. 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.

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/default.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.

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.