# Build a custom Front App with React, Vite & Shadcn

This guide introduces the **React Shadcn Vite** application template, a developer-oriented starter kit for building fully custom front-end applications on top of the Data Platform [Front API](/en/technical/sdk/api/index.md).

This template gives **full control over application code**, allowing developers to build tailored data applications using modern front-end technologies. For a low-code drag-and-drop experience, use the [visual App Manager](/en/product/app-manager/index.md).

!> This is an advanced template for developers comfortable with **React, TypeScript, and modern front-end tooling**. For a no-code approach, head to the [App Manager Getting Started guide](/en/getting-started/app-init/app-manager).

---

## Prerequisites

To use this template, first complete the following steps on the Platform:

- A **Lakehouse Manager** schema has been built and populated.
- A **Data Processing Engine** workflow has been executed successfully.
- **Queries** have been created in the Analytics Manager.
- A **Front API** has been [deployed](/en/getting-started/app-init/api-manager) and is running.
- [Node.js](https://nodejs.org/) (v22 or above) has been installed on your machine.

---

## What's included

### Tech stack

| Technology | Purpose |
|---|---|
| [React](https://react.dev/) 19 | UI framework |
| [TypeScript](https://www.typescriptlang.org/) 5 | Type-safe development |
| [Vite](https://vite.dev/) 6 | Build tool & dev server |
| [Tailwind CSS](https://tailwindcss.com/) 4 | Utility-first CSS framework |
| [Shadcn/UI](https://ui.shadcn.com/) | Component library (based on Radix UI) |
| [React Router](https://reactrouter.com/) 7 | Client-side routing |
| [TanStack Query](https://tanstack.com/query) 5 | Server state & data fetching |
| [Zustand](https://zustand.docs.pmnd.rs/) | Client state management |
| [Recharts](https://recharts.org/) | Data visualization |
| [i18next](https://www.i18next.com/) | Internationalization (EN/FR) |

### Modules

The template comes with three built-in modules:

#### `ts-sdk` — Data Platform SDK

The core module that handles communication with the Platform. It provides:

- **`DataPlatformApi`**: An API service that manages two Axios instances — one for the Identity Access Manager (IAM) and one for the Front API.
- **Automatic token injection** via Axios interceptors on every request.
- **Query execution** through `POST /qb/query` to retrieve data from your Analytics Manager queries.
- **Application preferences** fetching for branding and authentication configuration.
- **Environment configuration** loaded from `public/environments-vars.json`.

#### `rts-authentication` — Authentication

A complete authentication system providing:

- **Login page** with support for standard credentials and OAuth providers.
- **Multi-Factor Authentication (MFA)**: email, SMS, and authenticator app.
- **Session management** with automatic refresh (every 15 minutes) and token expiration handling.
- **Password change** flow with strength validation.
- **Zustand-based session store** persisted in `localStorage`.

#### `rts-charts` — Chart components

Ready-to-use data visualization components built on Recharts:

- **`<Chart />`**: A wrapper component that accepts a `QueryRequest`, executes the query against the Front API, and renders the result.
- Supported chart types: **Bar chart**, **Line chart**, **Pie chart**.
- **`<Table />`**: A data table component for tabular query results.
- Built-in **loading and error states**.
- **Dictionary support** for translating field values into readable labels.

---

## Project structure

```
├── public/
│   └── environments-vars.json          # API & IAM endpoints configuration
├── src/
│   ├── main.tsx                        # Application entry point
│   ├── routes.tsx                      # Route definitions
│   ├── components/
│   │   └── ui/                         # Shadcn/UI components
│   ├── config/
│   │   └── i18n/                       # Translation files (EN/FR)
│   ├── contexts/                       # React contexts (Auth, Dictionaries, etc.)
│   ├── forepaas/                       # Data Platform modules
│   │   ├── ts-sdk/                     # SDK module
│   │   ├── rts-authentication/         # Authentication module
│   │   └── rts-charts/                 # Charts module
│   └── pages/
│       ├── Home.tsx                    # Landing page
│       └── dashboard/
│           ├── DashboardOne.tsx        # Example dashboard with PieChart + BarChart
│           └── DashboardTwo.tsx        # Example dashboard with LineChart + BarChart + Table
├── forepaas.json                       # Data Platform deployment configuration
├── vite.config.ts                      # Vite configuration
└── tailwind.config.ts                  # Tailwind CSS theming
```

---

## Getting started

### 1. Create the application on the Platform

From your Project's home page, click on the **+** sign in the App Manager module.

Select the **React Shadcn Vite** template from the store, fill in the application name, and confirm.

### 2. Configure the environment

The template connects to the Platform through two endpoints defined in `public/environments-vars.json`:

```json
{
  "IAM_URL": "https://<PROJECT_NAME>.eu.dataplatform.ovh.net/cam?app_id=<APP_ID>",
  "API_URL": "https://<PROJECT_NAME>.eu.dataplatform.ovh.net/<API_ID>"
}
```

| Variable | Description |
|---|---|
| `IAM_URL` | The Identity Access Manager endpoint, including your application ID. Used for authentication. |
| `API_URL` | The Front API endpoint. Used for executing queries and fetching data. |

?> When running locally, the SDK automatically looks for `environments-vars-override.json` first, allowing you to set local development endpoints without modifying the main config.

### 3. Run locally

```bash
npm install
npm run dev
```

The dev server starts on `http://localhost:3333`.

### 4. Build and deploy

```bash
npm run build
```

This generates a production-ready bundle in the `/production` folder. You can also use `npm run zip` to create a deployable archive.

On the Platform, the build and deploy process works the same way as described in the [App Manager deployment guide](/en/getting-started/app-init/app-manager?id=build-and-deploy-the-new-version-of-your-app).

---

## Working with queries

The template uses `QueryRequest` objects to fetch data from the Front API. A query request contains:

| Field | Description |
|---|---|
| `data.fields` | The attributes to retrieve, with compute modes (e.g. `select`, `sum`). |
| `scale.fields` | The dimensions to group by. |
| `filter` | Filter conditions to narrow the results. |
| `dynamic_parameters` | Parameters for dynamic filtering (e.g. date ranges). |
| `order` | Sort order for results. |
| `data.limit` | Maximum number of results to return. |

### Example: using the Chicago dataset

If you followed the [Getting Started tutorial](/en/getting-started/app-init/index), the template includes example dashboards compatible with the Chicago bike rides dataset.

**Average rides per day of the week** (PieChart):

```typescript
const query: QueryRequest = {
  data: {
    fields: { avg_rides_per_day_per_station: ["select"] }
  },
  scale: {
    fields: ["week_day"]
  },
  filter: {},
  dynamic_parameters: []
};
```

**Top 5 stations by total rides** (BarChart):

```typescript
const query: QueryRequest = {
  data: {
    fields: { rides: ["sum"] },
    limit: 5
  },
  scale: {
    fields: ["station_name"]
  },
  order: { rides: "desc" },
  filter: {},
  dynamic_parameters: []
};
```

These queries are rendered using the `<Chart />` component:

```tsx
<Chart
  title="Average rides per day"
  type="pie"
  query={query}
  dictionary={weekDayDictionary}
/>
```

?> The queries above use the same attributes (`avg_rides_per_day_per_station`, `rides`, `station_name`, `week_day`, `cat_temperature`) created during the [Analytics Manager step](/en/getting-started/app-init/query-builder) of the Getting Started tutorial.

---

## Customizing the template

This template is a **starting point**. You are expected to develop your own pages, components, and business logic on top of it. Here are a few common tasks:

### Add a new page

1. Create your component in `src/pages/`.
2. Add a route in `src/routes.tsx`.
3. Add a navigation link in `src/components/Menu.tsx`.

?> The template includes a [Plop](https://plopjs.com/) generator to scaffold new dashboard pages. Run `npm run plop` and follow the prompts.

### Add a new chart

Use the `<Chart />` component with your own `QueryRequest`:

```tsx
import Chart from "@forepaas/rts-charts/components/Chart";

<Chart
  title="My custom chart"
  type="bar"
  query={myQueryRequest}
/>
```

Supported types: `bar`, `line`, `pie`. For tabular data, use the `<Table />` component.

### Add translations

Translation files are located in `src/config/i18n/`. Add your keys to both `en.json` and `fr.json`, then use them with the `useTranslation` hook from i18next:

```tsx
const { t } = useTranslation();
return <h1>{t("my.translation.key")}</h1>;
```

### Customize the theme

Tailwind CSS theming is configured in `tailwind.config.ts`. The template uses CSS variables (HSL-based) for colors, supporting both light and dark modes.

Shadcn/UI components can be customized or extended using the [Shadcn CLI](https://ui.shadcn.com/docs/cli).

---

## Going further

- [Front API documentation](/en/technical/sdk/api/index.md) — Learn how to customize and extend your API.
- [Identity Access Manager](/en/product/iam/index.md) — Configure authentication providers and access rights.
- [Analytics Manager](/en/product/am/index) — Create and manage your queries.
- [App Manager documentation](/en/product/app-manager/index.md) — Learn about the visual no-code alternative.