# preference-center-web ## Prerequisites 1. Make sure you have [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) and [pnpm](https://pnpm.io/installation) installed. (Alternatively, run `corepack enable` to enable `pnpm` in the installed version of Node.js.) 2. We are using private npm packages from our [monorepo](https://github.com/theorchard/orchard-suite). Follow this guide on how to set up NPM access: [Javascript Package Setup](https://www.notion.so/Javascript-Package-Management-Setup-9553d5d491c94835aa787fdf0fc4838d). 3. We recommend using [awsume](https://awsu.me/) to generate AWS CLI credentials. Follow this guide on how to set up AWS CLI: [AWS CLI Setup](https://www.notion.so/AWS-Access-f841b9dd815d4443a80e96a86c92cd2f#f11f08d09f16493a8a3e9dbf38d87164). You'll need to have `fansifter-role` to get access to m2m token ## Setup ```bash # Use supported Node version nvm use # Install dependencies pnpm # Create environment configuration cp .env.shadow .env # Start dev server pnpm dev ``` ## Available Scripts > **NOTE:** Running the project locally requires an active VPN connection. In the project directory, you can run: ### `pnpm dev` Starts Next.js in development mode with Hot Module Reloading, error reporting, and more. ### `pnpm test` Runs unit tests. Run this before creating a PR. ### `pnpm test:watch` Runs unit tests in "watch" mode in the development environment and "run" mode in CI automatically. ### `pnpm lint` Runs Biome linter for all files. ### `pnpm lint:fix` Runs Biome linter and automatically fixes issues. ### `pnpm check` Runs Biome check for all files (linting and formatting). ### `pnpm format` Formats code with `biome`. ### `pnpm format:check` Checks code formatting. ### `pnpm generate:openapi-types` Uses `openapi-typescript` to generate TypeScript types for connectors. ### `pnpm generate:next-types` Generates Next.js TypeScript types. ### `pnpm typecheck` Runs type checking on all TypeScript files. ### `i18n:init` Initializes locale dictionaries setup. ### Note that the following commands are not required to run locally: ### `pnpm build` Creates an optimized production build of your application, displaying information about each route. ### `pnpm start` Starts Next.js in production mode. The application should be compiled with `pnpm build` first. ### `check:ci` Checks formatting, runs linters, and unit tests in CI mode. ### `i18n:sync` Synchronizes locale dictionaries with POEditor. ## Mock Server The app includes a built-in mock server (MSW) for local development without a live API. It intercepts all outbound API requests on the server and returns configurable stub responses. ### Enabling Set `MOCK_API=true` in your `.env` file (only takes effect when `NODE_ENV=development`): ```env MOCK_API=true ``` Then start the dev server as usual with `pnpm dev`. ### Mock Toolbar When enabled, a "Mock server" button appears in the bottom-right corner of the page. Click it to expand a panel where you can: - **Switch endpoint behaviors** - each API endpoint has named presets (e.g. `200 OK`, `404 Not found`, `500 Server error`). Changes take effect immediately without a page reload. - **Set response delay** - simulates slow network conditions (milliseconds). - **Reset** - restores all endpoints and delay to their defaults. ### Adding new behaviors Behaviors are defined in `src/mocks/definitions.ts`. Each entry under a path+method key is a named preset with a `label` (shown in the toolbar) and a `response` function that returns the stub body and status. ## Running the application via Docker Ensure you have Docker installed and running on your machine. To run the application using Docker, follow these steps. ### Step 1: Build the Docker image First, build the Docker image with the necessary environment variables. Make sure you have set your `GITHUB_NPM_TOKEN` and any other optional environment variables. You can set them in your terminal session: ```bash export GITHUB_NPM_TOKEN=your_actual_token_here ``` Then, build the Docker image using the following command: ```bash docker build --build-arg GITHUB_NPM_TOKEN=$GITHUB_NPM_TOKEN -t pref-center-web . ``` ### Step 2: Run the Docker container Once the image is built, you can run the application in a Docker container. Make sure you have an `.env` file with all necessary environment variables. Then use the following command: ```bash docker run --env-file .env --rm -it -p 3000:8080 pref-center-web ``` The application will be accessible at `http://localhost:3000`. ### Example with optional arguments If you want to pass additional arguments, such as custom stage or other parameters, you can specify them using the `--target` option and any other necessary flags. Here's an example: ```bash docker build --build-arg GITHUB_NPM_TOKEN=$GITHUB_NPM_TOKEN \ --build-arg POEDITOR_PROJECT_ID=$POEDITOR_PROJECT_ID \ --build-arg POEDITOR_API_TOKEN=$POEDITOR_API_TOKEN \ --target builder \ -t pref-center-web . ``` ### Setting up Datadog for Standalone Next.js To ensure Datadog traces Server Actions and API routes correctly in the standalone build, we must load the tracer before Next.js starts. **Requirements & Steps**: 1. **Force External Packaging**: Add `dd-trace` to `serverExternalPackages` in `next.config` to prevent bundler from trying to tree shake it. 2. **Trigger Bundle Inclusion**: Add a dynamic import for `dd-trace` inside `instrumentation.ts` (`nodejs` runtime only). - Why? This forces Next.js to copy the `dd-trace` files into the `.next/standalone` folder during the build, even though we don't initialize it there. 3. **Avoid Double Initialization**: Do not call `.init()` inside `instrumentation.ts`. - Why? If Next.js loads before `dd-trace`, automatic instrumentation (tracing HTTP requests/Server Actions) will fail. 4. **Preload at Startup**: Initialize Datadog using a separate file (e.g., `dd-init.mts`) and load it using the `--import` flag before the server starts.