PrimeStore — E-Commerce Storefront

A modern, responsive fashion storefront built with Next.js, React, TypeScript, and CSS.

PrimeStore is a personal learning project focused on understanding modern frontend development through the implementation of a fashion e-commerce experience. It explores reusable components, dynamic routing, product presentation, client-side state management, and persistent shopping cart data.

Project status: In development
Project type: Personal learning project
Primary goal: Learn and apply Next.js and modern React development practices.

---

Table of Contents

• Overview
• Screenshots
• Features
• Technology Stack
• Architecture and Project Structure
• How the Application Works
• Design System
• Getting Started
• Available Scripts
• Learning Objectives
• Current Limitations
• Future Improvements
• Troubleshooting
• Author

---

Overview

PrimeStore is a fashion e-commerce storefront concept designed around a minimalist interface, a neutral color palette, and a simple shopping experience.

The application brings together a product catalog, individual product pages, product variant selection, and a shopping cart. Its codebase is organized into separate pages, reusable UI components, and a centralized product data module.

This project is being developed as a practical way to learn Next.js and React. Rather than focusing only on isolated exercises, I am exploring how the pieces of a web application work together.

Project Goals

• Understand the Next.js App Router and file-based routing.
• Build reusable and maintainable React components.
• Use TypeScript to describe data structures and function contracts.
• Manage shared application state with React Context.
• Persist shopping cart information in the browser.
• Create responsive layouts for different screen sizes.
• Develop a consistent visual identity through a reusable design system.
• Practice debugging, code organization, and incremental development.

Screenshots

Screenshots help visitors understand the application's interface before running the project.

The images below are intended to document the current implementation. Add your own screenshots to the repository using the directory structure shown here.

Recommended Screenshot Structure

PrimeStore/
├── docs/
│   └── screenshots/
│       ├── homepage.png
│       ├── product-details.png
│       ├── shopping-cart.png
│       └── mobile-view.png
├── next-app/
└── README.md

Homepage

The homepage presents the storefront's visual identity, promotional hero section, product categories, and product catalog.

Product Details

The product details page provides an individual product view with its images, description, available sizes, colors, quantity selection, and add-to-cart interaction.

Shopping Cart

The shopping cart displays selected products, their variants, quantities, line totals, and the subtotal.

Responsive Mobile Layout

The responsive layout adapts the storefront to smaller screens, making the interface more usable on mobile devices.

Note: These image paths are placeholders until you add the corresponding screenshot files. The images will not display on GitHub until the files exist at those paths.

How to Capture Screenshots

1. Start the development server using npm run dev.
2. Open http://localhost:3000 in your browser.
3. Navigate to the page you want to document.
4. Capture the page using your operating system's screenshot tool or the browser's screenshot functionality.
5. Save the images in docs/screenshots/ using the filenames listed above.
6. Commit and push the images together with the updated README.

For a professional presentation, use consistent browser zoom, capture the complete relevant interface, avoid including personal information, and use clear filenames.

---

Features

Storefront and Product Catalog

• Homepage with a promotional hero section.
• Product cards with images, names, categories, and prices.
• Product category filters.
• Search interface for finding products.
• Responsive product grid.
• Consistent buttons, spacing, typography, and visual styling.

Product Details

• Individual product pages using dynamic routes.
• Product image gallery with selectable thumbnails.
• Product descriptions and pricing.
• Size and color selection.
• Quantity selection.
• Add-to-cart interaction.
• Navigation between the catalog, product details, and shopping cart.

Shopping Cart

• Add products to the cart.
• Increase the quantity of existing cart items.
• Track different variants of the same product separately.
• Update quantities and remove individual items.
• Clear the entire cart.
• Calculate the total number of items and the subtotal.
• Persist cart data in the browser using localStorage.

Responsive Design

• Layout adjustments for desktop, tablet, and mobile screens.
• Flexible product grids.
• Mobile-friendly product detail layouts.
• Responsive navigation and cart presentation.
• Accessible focus indicators for interactive elements.

Feature availability depends on the current implementation. Search, filtering, checkout, and other interactions should be tested against the actual application before being described as production-ready.

---

Technology Stack

Technology	Role in the Project
Next.js	Application framework, routing, and page rendering
React	Component-based user interface
TypeScript	Static typing and clearer data contracts
Tailwind CSS	Utility-first styling framework included in the project
CSS	Global styling, layout rules, responsive behavior, and design system
React Context	Shared shopping cart state
React Hooks	State management, side effects, and memoized calculations
Browser localStorage	Client-side shopping cart persistence
npm	Dependency installation and project scripts
Git and GitHub	Version control and project hosting

Why These Technologies?

Next.js

Next.js provides a framework for building React applications with routing and rendering features.

PrimeStore uses the App Router, where folders and files inside the app directory define the application's routes. This reduces the need to configure a separate routing library for the main pages.

Dynamic route segments, such as products/[slug], allow multiple products to share the same page implementation while displaying different data.

React

React makes it possible to divide the interface into smaller, reusable components.

For example, ProductCard can render different products using the same component structure. This reduces duplicated markup and makes visual improvements easier to apply consistently.

TypeScript

TypeScript adds static type checking to JavaScript.

The Product type defines the expected structure of product information. Cart types define quantities, selected sizes, colors, and the functions exposed by the cart context.

These definitions help catch certain mistakes during development and make the code easier to understand and maintain.

Tailwind CSS and Custom CSS

Tailwind CSS provides utility classes for styling components. The project also uses custom CSS to manage its visual identity and detailed layout rules.

The global stylesheet centralizes colors, typography, borders, responsive breakpoints, and component styles. This approach provides a consistent appearance while allowing me to practice and understand CSS fundamentals.

React Context

The shopping cart needs to be accessible from multiple parts of the application.

React Context provides a shared interface for cart operations, allowing the header, product pages, and cart page to access the same cart state without passing every function and value through multiple layers of components.

React Hooks

The project uses several React Hooks for specific purposes:

• useState stores changing values, such as cart items and whether the cart has finished loading.
• useEffect performs side effects, such as loading and saving cart data.
• useCallback memoizes cart functions between renders when their dependencies remain unchanged.
• useMemo memoizes derived values, including the item count, subtotal, and context value.
• useContext provides access to the shared cart context.

These hooks help organize state and behavior according to React's component model. Memoization is used where appropriate; it is not a substitute for measuring application performance.

localStorage

The browser's localStorage API stores the cart as JSON so it can remain available after a page refresh.

This is useful for learning client-side persistence without building a backend first. However, local storage is limited to a browser and device, is accessible to client-side JavaScript, and should not be treated as a secure database or trusted source for prices.

---

Architecture and Project Structure

The Next.js application is located inside the next-app directory.

PrimeStore/
├── README.md
├── docs/
│   └── screenshots/
└── next-app/
    ├── public/
    ├── src/
    │   ├── app/
    │   │   ├── cart/
    │   │   │   └── page.tsx
    │   │   ├── products/
    │   │   │   └── [slug]/
    │   │   │       └── page.tsx
    │   │   ├── globals.css
    │   │   ├── layout.tsx
    │   │   └── page.tsx
    │   ├── components/
    │   │   ├── CartProvider.tsx
    │   │   ├── ProductCard.tsx
    │   │   ├── ProductDetailsClient.tsx
    │   │   └── StoreHeader.tsx
    │   └── data/
    │       └── products.ts
    ├── package.json
    └── tsconfig.json

This structure represents the intended organization of the project. Some generated Next.js files and configuration files may be omitted from this overview.

Application Routes

Route	Purpose
/	Homepage and product catalog
/products/[slug]	Individual product details
/cart	Shopping cart and order subtotal

The [slug] segment is a dynamic route. For example, a product with the slug classic-hoodie can be displayed at /products/classic-hoodie.

Key Files

src/app/page.tsx

Defines the homepage and brings together the storefront sections, product catalog, and reusable components.

src/app/layout.tsx

Defines the shared application layout and global styles. It also wraps the application with CartProvider so that the cart context can be accessed by its child components.

src/app/cart/page.tsx

Displays the cart items, selected variants, quantity controls, line totals, and subtotal.

src/app/products/[slug]/page.tsx

Finds the product associated with the requested slug and renders the product detail component. Unknown slugs should return a not-found page.

src/components/StoreHeader.tsx

Contains the shared storefront header, navigation, and cart indicator.

src/components/ProductCard.tsx

Displays a product preview in the catalog. Reusing this component keeps the product cards visually consistent.

src/components/ProductDetailsClient.tsx

Implements interactive product details, including image selection, size and color options, quantity selection, and adding a product to the cart.

src/components/CartProvider.tsx

Defines the cart context and the operations used to add, update, remove, and clear items. It also loads and saves the cart in localStorage.

src/data/products.ts

Contains the product data and the Product type. Keeping the sample catalog separate from the page components makes the data easier to maintain.

src/app/globals.css

Defines the global styles and the visual design system, including colors, typography, layout, component appearance, and responsive behavior.

---

How the Application Works

1. Product Data

Product information is defined in src/data/products.ts.

Each product includes information such as:

• A unique identifier.
• A URL-friendly slug.
• A product name and category.
• A price.
• An image and additional gallery images.
• A description.
• Available sizes and colors.

The shared Product type describes this structure so components can use product information consistently.

The current data source is local to the application. A future backend or product API could replace it without requiring the entire interface to be rebuilt.

2. Dynamic Product Pages

The App Router uses the product slug to identify which product to display.

The product page looks up the matching item in the product data and passes it to ProductDetailsClient. The same component can therefore render different products based on the route.

This demonstrates how route parameters can connect URLs with application data.

3. Product Variants

A product may be available in different sizes and colors.

The selected options are passed to the cart when a product is added. The cart treats combinations of product ID, size, and color as separate variants.

For example, a medium black T-shirt and a large black T-shirt can be represented as different cart entries.

4. Shared Cart State

CartProvider wraps the relevant application components and exposes cart operations through React Context.

When a product is added, the provider checks whether the same product variant already exists. If it does, the quantity increases; otherwise, a new cart entry is created.

The provider also calculates the total number of units and the subtotal based on the product data.

5. Browser Persistence

After the initial cart load, changes are saved to localStorage.

When the application starts, it attempts to read the saved cart and restore valid entries. This allows the cart to survive page refreshes in the same browser.

Because the application does not currently use a backend, this persistence is local to the user's browser rather than a server-side account.

6. Page Rendering

The project combines server-rendered route components with client-side interactive components.

For example, the dynamic product page can identify the product on the server, while the product detail client component handles interactive selections and cart actions.

This separation helps distinguish page-level data selection from browser interactions.

---

Design System

PrimeStore uses a minimalist fashion-store aesthetic with warm neutral surfaces, dark typography, and a bright lime accent.

The palette is designed to create a clear visual hierarchy without making the interface feel overly busy.

Color Palette

Color Name	Hex Value	Primary Use
Warm Off-White	#F8F8F5	Main page background
Charcoal Black	#191A17	Primary text and buttons
Lime Green	#D9FA61	Highlights, active filters, and badges
Muted Gray	#77786F	Secondary text and descriptions
Light Gray	#E5E5DF	Borders and separators
White	#FFFFFF	Cards and input surfaces
Muted Olive	#858A62	Secondary accents and highlights

Why These Colors Were Chosen

Warm Off-White — #F8F8F5

The warm off-white background is less stark than pure white. It provides a neutral canvas for product photography and supports the store's editorial, minimalist aesthetic.

Charcoal Black — #191A17

Charcoal is used for primary text and important actions. It creates strong contrast against light surfaces and gives buttons and headings a clear visual presence.

Lime Green — #D9FA61

Lime green introduces energy into the otherwise restrained palette. It draws attention to active filters, promotional badges, and selected visual elements.

Using it as an accent rather than the dominant background helps maintain a balanced interface.

Muted Gray — #77786F

Muted gray establishes a hierarchy between primary and secondary information. It is used for supporting descriptions and category labels so that product names and prices remain prominent.

Light Gray — #E5E5DF

Light gray provides subtle separation between sections, cards, and controls. It helps structure the interface without adding heavy visual borders.

White — #FFFFFF

White surfaces distinguish cards and form controls from the main background. This creates a subtle sense of depth while preserving the clean appearance.

Muted Olive — #858A62

Muted olive connects the neutral colors with the lime accent. It provides a softer alternative to the brighter accent for secondary highlights and decorative details.

Typography and Layout

The design uses bold headings, compact labels, and readable body text to establish visual hierarchy.

The layout relies on consistent spacing, flexible grids, restrained borders, and clear button styles. Responsive CSS media queries adapt the presentation for smaller screens.

Accessibility Considerations

The project includes visible focus indicators for interactive elements and uses semantic HTML elements where appropriate.

Color should not be the only way to communicate an interaction state. Text labels, selected-state indicators, meaningful alternative text, and keyboard navigation should continue to be checked as the project evolves.

---

Getting Started

Follow these steps to run PrimeStore locally.

Prerequisites

Install the following tools:

• Node.js: A version supported by the Next.js version installed in the project.
• npm: Included with Node.js.
• Git: For cloning the repository.

You can check your installed versions with:

node --version
npm --version
git --version

1. Clone the Repository

git clone https://github.com/Taunt-byte/PrimeStore.git

2. Navigate to the Application Directory

cd PrimeStore/next-app

3. Install Dependencies

npm install

4. Start the Development Server

npm run dev

5. Open the Application

Visit:

http://localhost:3000

The development server will display updates as you modify the application files.

Build for Production

To check whether the application can be compiled for production, run:

npm run build

To start the production server after a successful build, run:

npm run start

These commands assume that the corresponding scripts are defined in package.json, as in a standard Next.js project.

---

Available Scripts

The exact scripts depend on the current package.json. A typical Next.js setup includes:

Command	Purpose
npm run dev	Starts the development server
npm run build	Creates a production build
npm run start	Runs the production server
npm run lint	Runs linting if the script is configured

If a command is unavailable, check the scripts section of next-app/package.json. Do not add a script to this table as an available command until it exists in the project.

---

Learning Objectives

PrimeStore is an opportunity to learn by building and improving a complete frontend application.

The main areas of practice include:

• Next.js: App Router, dynamic routes, page composition, and rendering strategies.
• React: Component composition, props, client-side interactions, and shared state.
• TypeScript: Data types, function signatures, and safer component interfaces.
• State management: Managing cart entries and product selections.
• Browser APIs: Persisting state using localStorage.
• CSS: Layout systems, responsive breakpoints, visual hierarchy, and accessibility.
• Project organization: Separating routes, reusable components, and data.
• Debugging: Identifying errors, testing changes, and improving code incrementally.
• Documentation: Explaining implementation choices and maintaining a clear project README.

The objective is not only to build a storefront, but also to understand why each part of the application exists and how the pieces work together.

---

Current Limitations

PrimeStore is a learning project and is not yet a production-ready e-commerce platform.

Current limitations include:

• Product information is stored in local project data.
• Product images depend on external image URLs.
• Cart persistence is limited to the current browser and device.
• There is no backend database or inventory management system.
• User authentication and customer accounts are not implemented.
• Checkout and payment processing are not implemented.
• Local storage is not a trusted source for prices or other sensitive information.
• Product search, filtering, accessibility, and error handling require further testing before production use.

These limitations define areas for future development rather than implying that the current implementation already includes them.

---

Future Improvements

Potential next steps include:

Store Functionality

• Connect the catalog to a backend or product API.
• Add product sorting and improve search and filtering.
• Introduce stock availability and inventory validation.
• Add customer accounts and authentication.
• Implement a checkout workflow and integrate a payment provider.

Engineering Quality

• Add unit and component tests.
• Add end-to-end tests for browsing and cart interactions.
• Improve validation and error handling.
• Review accessibility and keyboard navigation.
• Add loading states and empty states where needed.
• Validate product and cart data more rigorously.
• Introduce server-side persistence if the application gains a backend.

Design and Deployment

• Add real project screenshots and keep them updated.
• Refine the mobile experience.
• Improve metadata and social sharing previews.
• Configure deployment and production environment settings.
• Add a live demo link when a stable deployment is available.

---

Troubleshooting

The Development Server Does Not Start

Confirm that you are inside the next-app directory and that dependencies have been installed.

cd PrimeStore/next-app
npm install
npm run dev

A Module Cannot Be Found

Check that the imported file exists and that the relative import path is correct. This project uses relative imports between local files, so the directory depth matters.

The Cart Does Not Persist

Check whether browser storage is enabled and whether the browser reports any storage-related errors. Cart data is stored locally and is not synchronized across devices.

A Product Page Returns Not Found

Confirm that the product slug in the URL matches a slug defined in src/data/products.ts.

A Screenshot Does Not Appear on GitHub

Check that the image exists at the exact path used in the Markdown image link. GitHub paths are case-sensitive, so filenames and directory names must match.

---

Author

Lucas Neves da Silva

Computer Engineering student interested in software development, web technologies, and game development.

• GitHub: @Taunt-byte

---

Acknowledgments

PrimeStore is a personal learning project developed while exploring Next.js, React, TypeScript, and modern frontend development.

The project reflects an ongoing learning process: building features, understanding the underlying concepts, troubleshooting problems, and improving the implementation over time.

---

Built for learning, experimentation, and continuous improvement.