--- name: replit-install-auth description: | Set up a Replit project with .replit + replit.nix configuration, Secrets, and Replit Auth. Use when creating a new Replit App, configuring Nix packages, managing secrets, or adding user authentication with Replit Auth. Trigger with phrases like "setup replit", "replit auth", "replit nix config", "replit secrets", "configure replit", "new replit project". allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(nix:*), Grep version: 1.0.0 license: MIT author: Jeremy Longshore compatible-with: claude-code, codex, openclaw tags: [saas, replit, authentication, nix, secrets, configuration] --- # Replit Install & Auth ## Overview Set up a Replit App from scratch: configure `.replit` and `replit.nix`, manage Secrets (AES-256 encrypted environment variables), and integrate Replit Auth for zero-setup user authentication with Google, GitHub, Apple, X, and Email login. ## Prerequisites - Replit account (Free, Core, or Teams plan) - Replit App created from template, GitHub import, or blank - For Auth: deployed app on `.replit.app` or custom domain ## Instructions ### Step 1: Configure `.replit` File ```toml # .replit — controls run behavior, deployment, and environment entrypoint = "index.ts" run = "npm start" # Nix modules provide language runtimes modules = ["nodejs-20:v8-20230920-bd784b9"] [nix] channel = "stable-24_05" [env] NODE_ENV = "development" PORT = "3000" [deployment] run = ["sh", "-c", "npm start"] deploymentTarget = "autoscale" build = ["sh", "-c", "npm run build"] ignorePorts = [3001] [unitTest] language = "nodejs" [packager] language = "nodejs" [packager.features] packageSearch = true guessImports = true [gitHubImport] requiredFiles = [".replit", "replit.nix"] ``` ### Step 2: Configure `replit.nix` ```nix # replit.nix — system-level dependencies via Nix { pkgs }: { deps = [ pkgs.nodejs-20_x pkgs.nodePackages.typescript-language-server pkgs.nodePackages.pnpm pkgs.postgresql pkgs.python311 pkgs.python311Packages.pip ]; } ``` After editing `replit.nix`, reload the shell for changes to take effect. ### Step 3: Configure Secrets Secrets are encrypted with AES-256 at rest and TLS in transit. Two scopes: - **App-level**: specific to one Replit App - **Account-level**: shared across all your Apps ```markdown Via UI: 1. Click the lock icon (Secrets) in the left sidebar 2. Add key-value pairs: - DATABASE_URL = postgresql://... - API_KEY = sk-... - JWT_SECRET = your-jwt-secret Via code — validate at startup: ``` ```typescript // src/config.ts function requireSecrets(keys: string[]): Record { const missing = keys.filter(k => !process.env[k]); if (missing.length > 0) { console.error(`Missing secrets: ${missing.join(', ')}`); console.error('Add them in the Secrets tab (lock icon in sidebar)'); process.exit(1); } return Object.fromEntries(keys.map(k => [k, process.env[k]!])); } const config = requireSecrets(['DATABASE_URL', 'JWT_SECRET']); ``` Secrets sync automatically between Workspace and Deployments. Replit's Secret Scanner warns if you paste API keys directly into code files. ### Step 4: Add Replit Auth Replit Auth provides zero-setup authentication. Users log in with Google, GitHub, Apple, X, or Email. Replit handles sessions via cookies, password resets, and user management. **Express.js integration:** ```typescript // src/auth.ts import express from 'express'; const app = express(); // Replit Auth injects these headers on authenticated requests interface ReplitUser { id: string; // X-Replit-User-Id name: string; // X-Replit-User-Name bio: string; // X-Replit-User-Bio url: string; // X-Replit-User-Url image: string; // X-Replit-User-Profile-Image roles: string; // X-Replit-User-Roles teams: string; // X-Replit-User-Teams } function getReplitUser(req: express.Request): ReplitUser | null { const id = req.headers['x-replit-user-id'] as string; if (!id) return null; return { id, name: req.headers['x-replit-user-name'] as string, bio: req.headers['x-replit-user-bio'] as string, url: req.headers['x-replit-user-url'] as string, image: req.headers['x-replit-user-profile-image'] as string, roles: req.headers['x-replit-user-roles'] as string, teams: req.headers['x-replit-user-teams'] as string, }; } // Auth middleware function requireAuth(req: express.Request, res: express.Response, next: express.NextFunction) { const user = getReplitUser(req); if (!user) return res.status(401).json({ error: 'Not authenticated' }); (req as any).user = user; next(); } // Client-side: GET /__replauthuser returns current user info // Login: direct user to Replit's login page for your app ``` **Flask integration:** ```python from flask import Flask, request, jsonify app = Flask(__name__) def get_replit_user(): user_id = request.headers.get('X-Replit-User-Id') if not user_id: return None return { 'id': user_id, 'name': request.headers.get('X-Replit-User-Name', ''), 'roles': request.headers.get('X-Replit-User-Roles', ''), 'teams': request.headers.get('X-Replit-User-Teams', ''), 'image': request.headers.get('X-Replit-User-Profile-Image', ''), } @app.route('/api/profile') def profile(): user = get_replit_user() if not user: return jsonify({'error': 'Not authenticated'}), 401 return jsonify(user) ``` ### Step 5: Verify Setup ```typescript // test-setup.ts — run to verify everything works const checks = { nix: process.version, // should show Node version secrets: !!process.env.DATABASE_URL, replSlug: process.env.REPL_SLUG, replOwner: process.env.REPL_OWNER, replId: process.env.REPL_ID, }; console.log('Replit Setup Verification:', checks); ``` Built-in environment variables available in every Repl: | Variable | Description | |----------|-------------| | `REPL_SLUG` | Your Repl's name/slug | | `REPL_OWNER` | Owner username | | `REPL_ID` | Unique Repl identifier | | `REPL_IDENTITY` | PASETO token signed by Replit infra | | `REPLIT_DB_URL` | Key-value database endpoint | ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | `Module not found` | Nix package missing | Add to `replit.nix` deps, reload shell | | `EACCES permission` | Wrong file permissions | Check `.replit` run command syntax | | `Secret undefined` | Not set in Secrets tab | Add via sidebar lock icon | | Auth headers empty | Not deployed / local dev | Auth only works on deployed `.replit.app` URLs | | `channel not found` | Invalid Nix channel | Use `stable-24_05` or check Nix channels list | ## Resources - [Replit App Configuration](https://docs.replit.com/replit-app/configuration) - [Using Nix with Replit](https://docs.replit.com/programming-ide/nix-on-replit) - [Replit Secrets](https://docs.replit.com/replit-workspace/workspace-features/secrets) - [Replit Auth](https://docs.replit.com/replit-workspace/replit-auth) ## Next Steps Proceed to `replit-hello-world` for a working starter app, or `replit-deploy-integration` to deploy.