Frontend - Get Started

This guide shows how to run the frontend locally and explains the basics you need to start working comfortably.

Precise Alloy is a public starter template for teams building websites with Optimizely CMS. It is designed to be reused across companies and projects, so treat the structure and tooling here as a solid baseline rather than a strict rulebook. Your team may keep it as-is, or it may adapt naming, processes, and deployment details to fit a specific project.

The source repository for this template is GitHub.

Tech Stack

The frontend in this template is built with the following tools:

Technology	Purpose
React	UI component library
TypeScript	Type-safe JavaScript
Vite	Build tool and dev server
Bun	JavaScript runtime and package manager

The codebase also follows a few conventions that are useful to know early:

Atomic Design by Brad Frost for organizing components into atoms, molecules, organisms, templates, and pages.
CSS BEM for naming CSS classes.
HTTP/2 best practices for understanding how browsers load assets efficiently.

Prerequisites

Before you start, install the following tools:

Visual Studio Code (latest version)
VS Code is recommended because the template already fits well with its frontend tooling and extensions.
Bun (v1.2.16 or higher)
Bun is used as both the JavaScript runtime and the package manager. To check your version, run:
```
bun --version
```
Git (latest version)
You will need Git to clone the repository and work with branches.

VS Code Extensions

If you use VS Code, these extensions are the most useful starting point.

Required:

ESLint for code quality feedback while you work.
XML Tools for working with XML and SVG files.
Prettier - Code formatter for consistent formatting.

Recommended:

Markdown All in One if you plan to update documentation.
markdownlint to keep Markdown files consistent.

Installation

Follow these steps to get the frontend running locally:

Clone the repository:

git clone https://github.com/precise-alloy/precise-alloy.git

Navigate to the Frontend folder:
```
cd precise-alloy/PreciseAlloy.Frontend
```
Install dependencies and start the dev server:
```
bun install
bun start
```
In this template, bun start runs the frontend development workflow, including the local server and file watching.
Open the site:
Once the server is running, open the local URL configured by VITE_PORT in PreciseAlloy.Frontend/.env. In this repository the default value is http://localhost:15889/.

If you need a different port or base path, update the relevant values in the frontend environment files before starting the server.

Project Structure

Here is a simplified view of the folders you will use most often:

src/
├── _api/       # API client modules
├── _data/      # Mock data and sample payloads
├── _helpers/   # Shared utility functions
├── _types/     # TypeScript type definitions
├── atoms/      # Small, reusable UI elements (buttons, inputs, etc.)
├── molecules/  # Combinations of atoms (search bars, form groups, etc.)
├── organisms/  # Complex UI sections (headers, footers, card grids, etc.)
├── templates/  # Page-level layouts that compose organisms
├── pages/      # Page-specific components and data
├── assets/     # Static assets (images, fonts, etc.)
├── configs/    # Sample configuration files
├── mocks/      # Mock service worker handlers
└── tests/      # Test files

This structure follows Atomic Design. When adding a component, start by deciding whether it belongs at atom, molecule, organism, template, or page level. Keeping that separation clear makes the project easier to maintain as more teams build on top of the template.

Project Resources

These links are useful when you are exploring the template or comparing your local setup with the reference implementation:

Resource	Link
Git repository	GitHub (base branch: `master`)
Design	Responsive Startup Website
Deployed site	https://alloy.eshn.dev/

What's Next?

Once the frontend is running, these guides are the best next read:

Development - learn about branching strategy, configuration, and the day-to-day workflow.
Coding Convention - understand the code style and rules we follow.
Browsers and Devices - see which browsers and devices we officially support.
Style Guide - review the design tokens and visual guidelines.
Testing - find out how to prepare your work for QA.

If you are using this repository as the base for a new project, this is also a good time to review environment variables, branding, and any sample content you plan to replace.