A Forio Epicenter simulation built from the
Epicenter React template (dev-base-build) and laid out so the platform's
pipeline feature can clone it from GitHub and build it on Epicenter.
The interface is a React + Vite + TypeScript app using the epicenter-libs v3
adapters, TanStack Query, Radix UI, CSS Modules and cva. The sim itself is the
template's "Bike Shop" Excel model.
- Repository layout
- Quick start
- .env configuration
- Project scripts
- Building on Epicenter with the pipeline
- Architecture overview • Routing & guards
• Authentication flow •
Data‑fetching conventions (
query/) • Extending the UI component system (components/ui/) - Internationalization (i18n)
The project uses Epicenter's rational (directory) layout: the platform clones
this repository into the project's src/ directory, so the repository root is
src/.
<repo>/
interface/ the npm project (Vite + React + TypeScript)
model/ model.xlsx and model.ctx2
pipeline/ copies of the *.cfg1 pipeline configs (live ones: config/pipeline on Epicenter)
tests/ parity and browser tests
update_notes/ reference material, discussion notes
notes/ conversion guides; epicenter_credentials_local.md is git-ignored
target/ git-ignored local build output, same shape as Epicenter's target/
npm run build(ininterface/) writes to../target/interface, the folder Epicenter serves at/app/{account}/{project}/. Inside the pipeline's build container the same path is/target/interface.npm run build:modelcopiesmodel/totarget/modellocally; on the platform the pipeline'scopyoperation does the same.- Do not nest the npm project under
src/in this repo: that would becomesrc/src/interfaceon the platform.
cd interface
# 1 Use the Node version declared in .nvmrc (the pipeline builds with Node 24)
nvm use
# 2 Install deps
npm install
# 3 Point .env at your account/project (see below)
# 4 Run the dev server
npm run dev # http://localhost:8888Production note When this bundle is served from
https://forio.com/app/<account>/<project>/…, Epicenter automatically reads the account and project from the URL and injects them into every API call. The.envfile is only used when you develop onlocalhost, because the browser URL no longer contains that information.
src/main.tsx switches the Epicenter SDK into local mode (config.isLocal() === true)
whenever the app is served by Vite. Provide the following variables in a top‑level
.env file:
| Variable | Example | Purpose |
|---|---|---|
VITE_DEV_ACCOUNT_SHORT_NAME |
acme-simulations |
Your Epicenter account slug |
VITE_DEV_PROJECT_SHORT_NAME |
supply-chain-game |
The project (simulation) slug |
VITE_DEV_API_HOST (optional) |
forio.com |
Override only if you proxy the Epicenter API |
If VITE_DEV_API_HOST is omitted it falls back to forio.com – the public cloud.
// src/main.tsx – excerpt
if (config.isLocal()) {
config.accountShortName = import.meta.env.VITE_DEV_ACCOUNT_SHORT_NAME;
config.projectShortName = import.meta.env.VITE_DEV_PROJECT_SHORT_NAME;
config.apiHost = import.meta.env.VITE_DEV_API_HOST; // default: "forio.com"
}Run these from interface/.
| Script | Description |
|---|---|
npm run dev |
Launches Vite with React Fast‑refresh on localhost:8888 |
npm run build |
Type‑checks (tsc -b) then builds a production bundle into ../target/interface |
npm run build:model |
Copies ../model to ../target/model |
npm run preview |
Serves the built bundle locally |
npm run lint |
ESLint + TypeScript rules (eslint.config.js) |
npm run deploy |
Build, then upload target/interface and target/model with the File API (fast iteration loop) |
npm run pipeline -- … |
Upload / run / list Epicenter pipeline configs (see below) |
npm run project -- … |
One-time project setup: create, access, web-access, git, git-status, info, files, rm |
npm run fixtures |
Creates the test group (pipeline-test) and adds the users listed in the credentials file |
npm run test:smoke |
API smoke test of the deployed sim: facilitator episode → participant run → model variables |
postinstall |
Applies any patch‑package overrides |
The CLIs read host:, author: and password: from the git-ignored
notes/epicenter_credentials_local.md (first occurrence of each wins) and the
account / project short names from interface/.env. Nothing secret goes into
git, tests or pipeline configs.
One-time setup (per project):
cd interface
npm run project -- create # creates the project with layout RATIONAL, accessType public
openssl genpkey -algorithm ed25519 -out /tmp/deploy-key.pem # PKCS#8 PEM, what Epicenter decodes
ssh-keygen -y -f /tmp/deploy-key.pem > /tmp/deploy-key.pub # OpenSSH public key line
# add /tmp/deploy-key.pub as a read-only deploy key on the GitHub repo, then:
npm run project -- git ssh://git@github.com/forio/forio-pipeline-example.git /tmp/deploy-key.pem /tmp/deploy-key.pub
npm run pipeline -- upload build # pipeline/build.cfg1 → config/pipeline/build.cfg1The project also needs Web Access: allow access to all URLs by default
(npm run project -- web-access allow, i.e. structure.enforceFilePermissions: false);
otherwise unauthenticated visitors are redirected to a login.html this app does not have.
Every build afterwards:
git push # the pipeline builds what is on GitHub
npm run pipeline -- run build # git sync → npm ci → npm run build → copy modelThe config (pipeline/build.cfg1) runs four operations: git (syncs src/ with
main, discarding local changes), two npm steps in a Node 24 container with
/src and /target mounted (working directory /src/interface), and copy
MODEL. pipeline/build-dev.cfg1 is the same for the develop branch.
Pipeline configs live outside the git checkout; re-upload from pipeline/ if
config/pipeline is empty after a reset.
npm run fixtures # once: test group + users (credentials file, git-ignored)
npm run test:smoke # logs in as facilitator + participant, creates a run, reads variablesThen open https://<host>/app/<account>/<project>/ and log in as a test user.
File‑based routes live under src/routes/. A single HashRouter tree is created in
main.tsx:
| URL | Guard | Shell | Purpose |
|---|---|---|---|
#/ |
RequireFocusedAuth |
PlayerShell |
Participant view |
#/facilitator |
RequireFocusedAuth |
FacilitatorShell |
Facilitator dashboard (lazy‑loaded) |
#/login |
RedirectIfAuthed |
– | Public login page |
#/logout |
– | – | Triggers authAdapter.logout() and clears local state |
RequireFocusedAuth– redirects to/loginunless a session + group exist.RedirectIfAuthed– keeps logged‑in users away from/login, forwarding them to the correct shell.
All auth calls use the authAdapter from epicenter-libs v3, wrapped in
TanStack Query mutations (src/query/auth.ts).
- Login
authAdapter.login({ handle, password, groupKey? })– if the response hasmultipleGroups: truewe fetch the list of groups, render a radio table, and re‑submit with a chosengroupKey. - Session regeneration Epicenter expires tokens after inactivity. Errors with codes
AUTHENTICATION_EXPIREDorAUTHENTICATION_INVALIDATEDtrigger theregenerateSession()helper, which callsauthAdapter.regenerate()and then retries the failed query transparently. - Logout (
#/logout) The dedicated route callsauthAdapter.logout(), clears the QueryClient, wipes Jotai atoms, and finally navigates to/login.
Every read lives in its own module, returning a queryOptions object. Components
consume them via useQuery(...).
- Include every variable the
queryFndepends on inqueryKey. This guarantees that a change in any dependency results in a new cache entry instead of stale data reuse. - Order key parts from broad → narrow. Doing so lets you selectively invalidate
coarse slices (e.g.
['episode']) without evicting unrelated child caches.
const current = ({ session }: { session: UserSession }) =>
queryOptions({
queryKey: ['episode', 'current', session.groupName, session.groupRole],
queryFn: async () => {
const [current] = await episodeAdapter
.query({
sort: ['-episode.created'],
max: 1,
})
.then((response) => response.values as Array<EpisodeReadOutView>);
if (current) return current;
if (session.groupRole === 'FACILITATOR') {
const episodeName = 'ep'.concat(Date.now().toString());
return episodeAdapter
.create(episodeName, session.groupName!)
.then((episode) => episode as unknown as EpisodeReadOutView);
}
throw new Error('No episode found');
},
staleTime: Infinity,
enabled: Boolean(session.groupName),
});When you pass this object to
useQuery(EpisodeQuery.current({ session }))the key is guaranteed to change wheneversession.groupNamedoes, which forces a refetch instead of leaking data across groups.
- CSS Modules – local, hashed class names.
- Radix UI primitives – accessibility & behaviour (e.g.
@radix-ui/react-dialog). - Design tokens – all colours, spacing, and radii live in
src/styles/tokens.scss(Radix colour scales mapped to CSS variables). cva(class‑variance‑authority) – declarative styling variants.
import { cva, type VariantProps } from 'class-variance-authority';
import styles from './tag.module.scss';
// 1 Define once
export const tagVariants = cva(styles.base, {
variants: {
intent: {
info: styles.info,
success: styles.success,
danger: styles.danger,
},
size: {
sm: styles.sm,
lg: styles.lg,
},
},
compoundVariants: [
{
intent: 'danger',
size: 'lg',
class: styles.dangerLgShadow,
},
],
defaultVariants: {
intent: 'info',
size: 'sm',
},
});
// 2 Consume in the component
export interface TagProps extends VariantProps<typeof tagVariants> {}
export const Tag: React.FC<React.PropsWithChildren<TagProps>> = ({ intent, size, children }) => (
<span className={tagVariants({ intent, size })}>{children}</span>
);Guidelines
- Keep layout (flex, grid) out of variants – reserve variants for visual‑state concerns (intent, size, emphasis).
- The first argument (
styles.base) should contain all structural CSS; variants add or override. - If a component accepts
asChild, remember to forward theclassNametoSlot.
This template includes built-in support for localization using react-i18next and the custom Lang component.
Translation files live under src/assets/lang/<language>/<namespace>.json and are loaded at build time via vite-plugin-i18next-loader. By default, the app is initialized with:
// src/main.tsx – excerpt
i18n.use(initReactI18next).init({
resources,
lng: 'en', // default language
fallbackLng: 'en', // fallback language
defaultNS: 'common', // default namespace
fallbackNS: 'common',
interpolation: { escapeValue: false },
});Use the Lang component to translate strings in your JSX:
import { Lang } from '~/components/lang';
// Default namespace ('common')
<Lang>sim_title</Lang>
// Specify another namespace (e.g. 'error')
<Lang ns="error">not_found</Lang>
// Interpolation via the `d` prop
<Lang ns="password-reset" d={{ handle: username }}>
no_account
</Lang>Lang props:
children: translation key (string)ns?: optional namespace (defaults tocommon)d?: optional dictionary for interpolationkp?: optional keyPrefix for nested keys
For more complex translations with JSX markup, use the Trans component from react-i18next:
import { Trans } from 'react-i18next';
<Trans ns="error" i18nKey="GENERIC_ERROR" components={{ 0: <a href="/logout" /> }} />Happy sim-building! 🚀