@persistent-ai/fireflow-frontend-app (0.29.4)
Installation
@persistent-ai:registry=npm install @persistent-ai/fireflow-frontend-app@0.29.4"@persistent-ai/fireflow-frontend-app": "0.29.4"About this package
@persistent-ai/fireflow-frontend-app
The deployable FireFlow SPA, published as an npm package.
@persistent-ai/fireflow-frontend publishes only dist/lib — the embeddable
React library. The single-page application that a browser actually loads is a
different build (vite build --config vite.app.config.ts → dist/app), and it
used to exist only inside the monorepo Docker image. This package publishes that
build so an environment that cannot mirror our container images can still deploy
the frontend: npm install the tarball, copy it into an nginx webroot, done.
See decision D-013 in the contour-deploy repository for the rationale.
Contents
dist/
app/ the SPA: index.html + hashed assets, serve as static webroot
deploy/
nginx.conf nginx server block (SPA fallback, cache and security headers)
env-config.js.template envsubst template for runtime configuration
docker-entrypoint.sh renders the template, gzips assets, then execs the command
Nothing here is imported as JavaScript — the package has no entry point. It is a file drop.
Consuming it
npm install @persistent-ai/fireflow-frontend-app
The package lives in GitHub Packages, so the consuming project needs
@persistent-ai:registry=https://npm.pkg.github.com (or an equivalent mirror)
in its .npmrc.
A minimal nginx image on top of it:
FROM node:24-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json .npmrc ./
RUN npm ci --omit=dev
FROM nginx:alpine
RUN apk add --no-cache gettext && mkdir -p /etc/nginx/templates
ENV PKG=/app/node_modules/@persistent-ai/fireflow-frontend-app/dist
COPY --from=deps /app/node_modules /app/node_modules
RUN cp -r $PKG/app/. /usr/share/nginx/html/ \
&& cp $PKG/deploy/nginx.conf /etc/nginx/conf.d/default.conf \
&& cp $PKG/deploy/env-config.js.template /etc/nginx/templates/env-config.js.template \
&& cp $PKG/deploy/docker-entrypoint.sh /docker-entrypoint.sh \
&& chmod +x /docker-entrypoint.sh
EXPOSE 3000
ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["nginx", "-g", "daemon off;"]
The paths baked into docker-entrypoint.sh are the ones used above:
it reads /etc/nginx/templates/env-config.js.template and writes
/usr/share/nginx/html/env-config.js. nginx.conf listens on port 3000 and
serves from /usr/share/nginx/html. Deviating from that layout means adjusting
the copied files.
Runtime configuration
The SPA reads its backend endpoints from window.__env__, which
/env-config.js defines. That file is generated at container start by
docker-entrypoint.sh (via envsubst), so one built artifact serves every
environment — no rebuild per deployment. nginx.conf marks index.html and
env-config.js as never-cached; every other asset is content-hashed and cached
for a year.
Variables the entrypoint substitutes:
| Variable | Default |
|---|---|
VITE_FIREFLOW_TRPC_WS_URL |
ws://localhost:3001 |
VITE_FIREFLOW_BACKEND_URL |
http://localhost:3001 |
VITE_FIREFLOW_EXECUTOR_WS_URL |
ws://localhost:4021 |
VITE_FIREFLOW_EXECUTOR_HTTP_URL |
http://localhost:4021 |
VITE_FIREFLOW_AUTH_URL |
(empty) |
VITE_FF_AUTH_REQUIRED |
false |
VITE_TELEGRAM_BOT_NAME |
(empty) |
VITE_PERF_TRACE_FRONTEND_DISABLED |
false |
env-config.js.template is the authoritative list; the table follows it.
Building it in the monorepo
pnpm --filter @persistent-ai/fireflow-frontend-app run build
scripts/build.mjs copies apps/fireflow-frontend/dist/app and the three
deployment files into dist/. Under turbo the SPA comes from the
@persistent-ai/fireflow-frontend#build:app task that this package's build
declares as a dependency, which keeps the result cacheable. Run standalone with
no SPA present, the script invokes that build itself.
The SPA build is memory-hungry — build:app already sets
--max-old-space-size=8192.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| @persistent-ai/fireflow-frontend | 0.29.4 |