Overview

In the services/remix directory you can find the “FE” code of the application - meaning the client code and also server code that acts as a “BFF” (backend for frontend).

This project utilizes Remix, which is a React-based full-stack web application framework that has great abstractions for client-side routing, data fetching and more.

Resources

  • For a deeper dive into specific topics (technical stack, testing, conventions, etc.), check out the adjacent documents.

  • Run the Vega storybook (npm run storybook) to see guides related to our design system, existing components and more.

  • See our Figma project for page mockups, design system guidelines and more.

Setup Environment

We recommend using VSCode/Cursor when working on FE, as we have predefined settings/tasks/extensions in our codebase for VSCode.

Contact Ofir if you want an invite to use Cursor.

Please ensure your the linter (eslint) and formatter (prettier) are configured correctly before pushing any new code, and that you have the VSCode extensions relevant for FE development installed (see .vscode/extensions.json).

Development

Local startup (basic)

  • Install Node.js version >= 20: brew install node

  • Make sure dependencies are installed and up to date: npm install

    • remember to run this command every time if you switch between branches that made changes to the package.json file. otherwise, it’s not necessary.

  • Run setup: npm run setup

  • Install required build dependencies before running the dev server:

  • Ensure environment variables are correctly set:

    • The required environment variables can be seen in app/utils/env.server.ts. Without them, the app will fail to load with an error of “Invalid environment variables”.

    • You can use the VSCode task “Start FE local” which ensures env variables are loaded and runs the dev server. For this to work, you need to export the env variables from a .env.local file at the root of the monorepo, in the following syntax:

      export SESSION_SECRET=...
...

  • Run the VSCode task “Start FE local” to load the env variables from .env.local and run the Express server with Vite dev middleware.

    • alternatively, you can run npm run dev to do the same thing, but you’ll need to manually load the env variables from wherever you have them.

  • We use remix-dev-tools (link) but hide them by default (because in some pages it overlaps “Next” buttons and that is problematic when running local E2E tests). To enable the dev tools, add rdt=true as a query param to the URL.

Local startup with Tilt

  • When you run tilt, the frontend will be available on http://localhost.
  • When you save files, the frontend docker in tilt is re-built, and afterwards your changes will be applied.
  • if you work with the dev server, you should disable the front service in Tilt, otherwise it will continue to be built for every change you make and this can cause

IMPORTANT: Tilt is currently running the frontend docker in deployment mode, not dev mode, so the docker’s update might take some time. If you change the frontend code frequently, you might want to run the frontend without tilt, like described above.

Local build & run

This way can be used if you want to build the frontend and run it in production mode, which is the closest way to see how the app will behave in production when running completely locally. Normally you shouldn’t need to do this (its also what Tilt does essentially - build the app inside a docker container), and instead build your branch and test against the ArgoCD Dev environment to ensure the setup is as close to production as possible.

  • Build your app for production: npm run build
  • Run the app in production mode: npm start

Debug local front against production environment

  1. Run the following commands to proxy to the production environment:
# ensure we are authenticated against teleport and the context is correct
tsh login --proxy=vega.teleport.sh:443 --auth=okta-integration

# setup the proxy
tsh proxy app vega --port 1337

  1. Run the “Start FE atomic” task in VSCode (or npm run dev:atomic from the command line but ensure env variables are loaded)

  2. Sign in through the proxy: navigate to http://localhost:1337, enter your work email, click “Email me a magic link”, then click the link from your inbox. After signing in, you should be able to work on http://localhost:3000 with production data.

Note: The magic link may sometimes fail and redirect you back to the localhost:1337 login page. If that happens, clear your cookies and repeat the sign-in process.

  1. Done! You should now be able to access the local FE app on http://localhost:3000, and the requests will be proxied to the production environment via http://localhost:1337.

Note: You can do the same to staging environment (https://staging.vega.io) or dev environment (https://dev.vega.io) by changing vega to vega-staging or vega-dev respectively in the tsh proxy command.

Debug local front against a devinci environment

Devinci named envs aren’t registered as Teleport apps, so tsh proxy app can’t reach them. Use the backend:devinci script instead — it port-forwards the env’s front and gateway services and serves both on http://localhost:1337, the same shape the env’s ALB has:

cd services/remix

# which envs exist right now
npm run backend:devinci -- --list

# attach to one (keep this running)
npm run backend:devinci -- <env-name>

Then continue exactly as with the production flow above: run npm run dev:atomic in another terminal, sign in once at http://localhost:1337, and work on http://localhost:3000.

The env must already be deployed — the script never deploys. If the namespace is missing it prints the /sam devinci deploy and gh workflow run deploy-dynamic-env.yml commands and exits.