Getting Started with Horizon Storefront

Welcome to the Horizon Storefront development guide. This page will help you get up and running with local development.

Prerequisites

Before you begin, ensure you have:

Node.js 22.x LTS or higher
pnpm 10.0.0 or higher
Git for version control
Access to the Horizon mono-repo

Quick Start

1. Clone the Repository

git clone https://github.com/templeandwebster/horizon.git
cd horizon

2. Install Dependencies

pnpm install

3. Start Development Server

pnpm run dev:storefront

The storefront will be available at http://localhost:3000.

Project Structure

apps/storefront/
├── src/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   ├── lib/              # Utilities and helpers
│   └── styles/           # Global styles
├── public/               # Static assets
└── package.json

Key Technologies

Next.js 16: React framework with App Router
React 19: UI library
TypeScript: Type-safe development
Tailwind CSS: Utility-first styling
Webster Design System: Component library

Development Workflow

Creating New Pages

Create a new directory in src/app/
Add a page.tsx file
Export a default React component

Example:

export default function ProductPage() {
  return (
    <div>
      <h1>Product Page</h1>
    </div>
  );
}

Using Components

Import components from Webster Design System:

import { Button, Card } from '@tpw/webster-ui';

export default function MyPage() {
  return (
    <Card>
      <Button>Click Me</Button>
    </Card>
  );
}

Styling

Use Tailwind CSS classes:

<div className="flex items-center gap-4 p-4 bg-white rounded-lg shadow">
  <h2 className="text-2xl font-bold">Title</h2>
</div>

Common Tasks

Running Tests

pnpm test

Linting

pnpm lint

Type Checking

pnpm type-check

Building for Production

pnpm build

Troubleshooting

Port Already in Use

If port 3000 is in use:

PORT=3001 pnpm run dev:storefront

Type Errors

Ensure all dependencies are installed:

pnpm install

Run type checking:

pnpm type-check

Cache Issues

Clear Next.js cache:

rm -rf .next
pnpm run dev:storefront

Next Steps

Explore the Architecture documentation
Review Component Patterns
Check API Integration
Read Performance Guidelines

Getting Help

Slack: #horizon-storefront
Email: storefront-tribe@templeandwebster.com.au
Issues: Create a ticket in Jira