This guide walks through setting up a full local development environment for Preoc Product Manager. You will cover everything from prerequisites and cloning the repository, to installing dependencies, configuring environment variables, and starting the Next.js development server — so you can immediately begin exploring or extending the construction product catalog.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sergio-salcedo-dev/excel-product-manager/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
Before you begin, make sure the following tools are available on your machine:- Node.js 18 or later — required to run Next.js 15
- npm, yarn, or pnpm — any of the major package managers work
- A Google Gemini API key — required for AI-powered CYPE Precios search; optional if you only need basic product CRUD and Excel import/export
- Git — to clone the repository
Installation
Create the environment file
Copy the values below into a new file named
.env.local at the project root. This file is read by Next.js at startup and is never committed to version control..env.local
NEXT_PUBLIC_GEMINI_API_KEY is your Google Gemini API key. The NEXT_PUBLIC_ prefix is required because the AI search calls in ProductDashboard run in the browser — Next.js only exposes environment variables to client-side code when they carry this prefix. Variables without it are server-only and will be undefined in the browser. The .env.example template in the repository uses the shorter plain name GEMINI_API_KEY (suitable for server-side contexts such as Firebase App Hosting secrets), but your local .env.local must use NEXT_PUBLIC_GEMINI_API_KEY. APP_URL tells the application its own base URL, which is used for self-referential links and API endpoints.Start the development server
Launch the Next.js development server with hot module replacement:Once the server is ready, open http://localhost:3000 in your browser. Any changes you make to source files are reflected immediately in the browser without a full page reload.
Available Scripts
All scripts are defined inpackage.json and run via your package manager’s run command.
| Script | Command | Description |
|---|---|---|
dev | next dev | Starts the Next.js dev server with hot module replacement |
build | next build | Creates an optimized production build in the .next directory |
start | next start | Serves the production build locally on port 3000 |
lint | eslint . | Runs ESLint across the entire project |
clean | next clean | Removes the .next build cache to force a clean rebuild |
Verifying the Setup
A healthy local environment looks like this:- The terminal shows the Next.js dev server listening on port 3000 with no compilation errors.
- Opening http://localhost:3000 displays the product dashboard pre-loaded with 20 default construction products — no database or network connection is required for the initial catalog, as it is stored in
localStorage. - Clicking the CYPE Precios button and entering a search term (for example,
cemento) returns AI-powered pricing results from the Gemini API, providedNEXT_PUBLIC_GEMINI_API_KEYis correctly set in.env.local. - The Export to Excel action downloads a file named
productos.xlsxcontaining the current catalog.
Common Issues
AI search returns an error
AI search returns an error
Check that
NEXT_PUBLIC_GEMINI_API_KEY is set in .env.local (not .env or .env.development). The NEXT_PUBLIC_ prefix is required — without it the variable is undefined in the browser and the Gemini client cannot initialize. Next.js only reads .env.local automatically in development. After adding or changing the key, stop the dev server and restart it with npm run dev — environment variables are read at startup and are not hot-reloaded.Products don't appear on refresh
Products don't appear on refresh
The product catalog is persisted in the browser’s
localStorage. localStorage is scoped to a browser profile, so data will not carry over to private/incognito windows or if you have cleared your browser data. In that case the application will re-load the default 20-product catalog automatically — no action is needed.Port 3000 is already in use
Port 3000 is already in use
Another process is already bound to port 3000. Either stop that service, or start the dev server on a different port:Remember to update
APP_URL in .env.local to match the new port (http://localhost:3001) if any feature depends on it.TypeScript errors on build
TypeScript errors on build
Run the linter first to surface formatting and import issues:The project is configured with
typescript.ignoreBuildErrors: false in next.config.ts, so TypeScript errors will fail the build. Ensure you are running Node.js 18 or later (node -v) and that all dependencies installed cleanly. If the .next cache appears corrupted, clear it with npm run clean before rebuilding.