Skip to main content
This guide will help you install and run Luz de Arcanos on your local machine.

​
Prerequisites

Before you begin, ensure you have:

​
Installation

1

Clone the repository

Clone the Luz de Arcanos repository to your local machine:
git clone https://github.com/RamirezDiazCarlos/TarotWeb.git
cd TarotWeb
2

Install dependencies

Install the required packages using Bun or npm:
bun install
The project uses these core dependencies:
  • astro (v5.17.1) — Framework with SSR support
  • @astrojs/vercel (v9.0.4) — Vercel adapter for deployment
  • @google/genai (v1.42.0) — Google Gemini AI SDK
3

Configure environment variables

Create a .env file in the root directory and add your Google Gemini API key:
.env
GEMINI_API_KEY=your_api_key_here
Get your free API key from Google AI Studio. The application will not function without this key.
4

Start the development server

Run the development server:
bun dev
The application will start at http://localhost:4321 by default.
5

Make your first consultation

Open your browser and navigate to http://localhost:4321. You’ll see:
  1. A form requesting your name and question
  2. After submitting, three cards will flip to reveal your reading
  3. The AI will generate a personalized interpretation
You’re limited to 5 consultations per day. This limit is stored in localStorage and resets after 24 hours.

​
Available scripts

The package.json includes these scripts:
package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
  • dev — Start the development server with hot reload
  • build — Build the application for production
  • preview — Preview the production build locally

​
Troubleshooting

​
API key not configured

If you see an error about GEMINI_API_KEY, ensure:
  1. Your .env file exists in the root directory
  2. The variable is named exactly GEMINI_API_KEY
  3. You’ve restarted the development server after creating the .env file

​
Rate limit errors (429)

The application automatically falls back between these Gemini models:
  1. gemini-2.5-flash (primary)
  2. gemini-2.0-flash (fallback)
  3. gemini-2.0-flash-lite (final fallback)
If all models fail, a static fallback reading is generated based on the drawn cards.

​
Client-side consultation limit

If you’ve reached the 5-consultation daily limit:
  1. Wait 24 hours for the limit to reset
  2. Or clear your browser’s localStorage for the site
  3. The limit is tracked using the key tarot_usage

​
Next steps

How it works

Understand the application flow and card drawing mechanism

View live demo

See the production version in action

Build docs developers (and LLMs) love

Get started for freeTalk to us