Quickstart Guide
Get Cajas up and running on your local machine in just a few minutes. This guide walks you through cloning the repository, setting up Supabase, and opening your first case.Prerequisites
Before you begin, make sure you have:- Node.js 20.x or later installed
- npm, yarn, pnpm, or bun package manager
- A Supabase account (free tier works perfectly)
- Git for cloning the repository
This guide uses npm commands, but you can substitute with your preferred package manager (yarn, pnpm, or bun).
Installation Steps
Clone the repository
Clone the Cajas repository to your local machine:This creates a local copy of the project in the
cajas-app directory.Install dependencies
Install all required npm packages:The project includes these key dependencies:
- npm
- yarn
- pnpm
- bun
next(16.0.6) - React framework@supabase/supabase-js(2.86.0) - Supabase client@supabase/ssr(0.8.0) - Server-side rendering supportframer-motion(12.23.25) - Animationsreact-hook-form(7.68.0) - Form handlingzod(4.1.13) - Schema validation
Set up Supabase project
Create a new Supabase project:
- Go to supabase.com and sign in
- Click New Project
- Choose a name, database password, and region
- Wait for the project to provision (takes ~2 minutes)
- Project URL (starts with
https://) anonpublic key (safe to use in client-side code)
Configure environment variables
Create a Add your Supabase credentials:These environment variables are used throughout the app:
.env.local file in the project root:.env.local
lib/supabase/server.ts
Run database migrations
Apply the database schema to your Supabase project:Option 1: Using Supabase Dashboard (Recommended)Then run the cases system migration:Finally, add the provably fair system:Option 2: Using Supabase CLIIf you have the Supabase CLI installed:
- Open your Supabase project dashboard
- Navigate to SQL Editor
- Run each migration file in order:
supabase/migrations/20240101000000_init.sql
supabase/migrations/0000_create_cases_system.sql
supabase/migrations/20251209000000_create_provably_fair.sql
Run migrations in numerical order. Each migration builds upon the previous one.
Start the development server
Start the Next.js development server:The server starts at http://localhost:3000.You should see output like:
- npm
- yarn
- pnpm
- bun
Create a test user
Open your browser to http://localhost:3000 and:
- Click Sign Up or Login in the navigation bar
- Create a new account with your email and password
- Check your email for a confirmation link (in development, check Supabase dashboard → Authentication → Users)
- Confirm your email to activate the account
Create and open your first case
Now let’s create a test case:Create an Admin UserFirst, promote your user to admin in the Supabase dashboard:Create a CaseNavigate to http://localhost:3000/admin/create-case and create a case with:The case opening animation uses a provably fair algorithm. Here’s how it works:
- Go to SQL Editor
- Run this query (replace with your user ID):
- Name: Starter Box
- Price: 1000
- Description: Your first case
- Image URL: Any image URL or upload
- Common Item (50% probability, value: 500)
- Rare Item (30% probability, value: 1500)
- Epic Item (15% probability, value: 3000)
- Legendary Item (5% probability, value: 10000)
- Navigate back to the homepage
- You’ll see your “Starter Box” case
- Click on it to open the case page
- Click Open Case to run your first opening!
Congratulations! You’ve successfully set up Cajas and opened your first case.
app/api/cases/open/route.ts
Verify Your Setup
To ensure everything is working correctly:Check database tables
Check database tables
In your Supabase dashboard, navigate to Table Editor and verify these tables exist:
userscasescase_itemsuser_seedsgame_rollstransactions
Test authentication
Test authentication
Try logging out and logging back in. Check that:
- You can sign up with a new email
- You receive confirmation emails
- Sessions persist across page refreshes
- Protected routes redirect to login
Test case opening
Test case opening
Open multiple cases and verify:
- Animations play smoothly
- Different items are won (based on probability)
- No console errors appear
- Items appear in your inventory
Check provably fair
Check provably fair
Navigate to
/provably-fair and verify:- Your server seed hash is displayed
- You can update your client seed
- Roll history is accessible
- Verification tools work correctly
Common Issues
Next Steps
Now that you have Cajas running locally:Explore Features
Learn about all the features available in Cajas, from provably fair mechanics to wallet management.
Deploy to Production
Deploy your Cajas instance to Vercel or another hosting platform.
Customize the UI
Modify colors, fonts, and layouts to match your brand.
Add Payment Methods
Integrate real payment processors like Stripe or Mercado Pago.
Development Tips
Need Help?
If you run into issues:- Check the GitHub Issues for known problems
- Review the Features Documentation for detailed explanations
- Join the community discussions
- Open a new issue with reproduction steps
You’re all set! Start building your case opening platform.
