DevFrame

DevFrame is a free and open-source portfolio builder for developers. Users sign in, choose a ready-made template, fill in a guided form, and publish a portfolio at a route like /p/regie.

This repo is set up as an open-source app starter with:

• Next.js 16 App Router
• Tailwind CSS 4
• shadcn-style UI primitives
• Clerk authentication
• Supabase PostgreSQL
• Supabase Storage-ready architecture
• React Hook Form + Zod
• Vercel-friendly deployment setup
• Optional community support through GitHub, GoTyme InstaPay, and GCash

What is included

• Marketing homepage for DevFrame
• Clerk sign-in and sign-up routes
• Protected dashboard, templates, and builder pages
• Template catalog with three starter portfolio styles
• Public portfolio route at /p/[slug]
• API routes for templates and public portfolio fetches
• Server action for saving portfolio data
• Cookie-backed preview mode when Supabase is not configured yet
• Supabase schema file for real persistence

Local setup

1. Install dependencies.

npm install

2. Copy the example environment file.

cp .env.example .env.local

3. Create a Clerk app and add:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
• CLERK_SECRET_KEY
• CLERK_AUTHORIZED_PARTIES if you want to override the default origin allowlist

DevFrame keeps Clerk as auth/session infrastructure only and uses custom auth screens. For Clerk CLI checks, OAuth redirects, and email template setup, see docs/clerk-auth-setup.md.

4. Create a Supabase project and add:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
• SUPABASE_SERVICE_ROLE_KEY

5. Run the SQL in supabase/schema.sql inside the Supabase SQL editor.

6. Start the app.

npm run dev

Open http://localhost:3000.

Before deploying to Vercel

• Set NEXT_PUBLIC_APP_URL to your production origin, for example https://your-domain.com.
• Clerk authorizedParties is now enforced in src/proxy.ts.
• By default it allows NEXT_PUBLIC_APP_URL plus the current Vercel deployment URL(s).
• If you want an explicit fixed allowlist, set CLERK_AUTHORIZED_PARTIES as a comma-separated list such as https://your-domain.com,https://your-project.vercel.app.
• For durable production rate limiting, set either UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN or Vercel KV's KV_REST_API_URL + KV_REST_API_TOKEN. If these are missing, DevFrame uses a per-instance in-memory fallback that is for local/dev only and is not durable security protection on Vercel serverless.
• Leave Vercel's Automatically expose System Environment Variables setting enabled so preview deployments can use VERCEL_BRANCH_URL, VERCEL_URL, and VERCEL_PROJECT_PRODUCTION_URL.

Recommended Vercel branch flow

Branch	Purpose	Vercel deployment
main	Production	Live site
staging	Testing	Preview
feature/*	Dev	Preview

If you want a real staging custom environment

• This requires a Vercel Pro or Enterprise plan.
• In Vercel, go to Project Settings -> Environments -> Create Environment.
• Create a custom environment named staging.
• Enable Branch Tracking and point it at the Git branch named staging.
• Add your staging environment variables there.
• Optionally attach a staging domain like staging.your-domain.com.
• After that, every push to the Git branch staging will automatically deploy to the Vercel environment staging, so vercel deploy --target=staging becomes optional.

Dashboard setup

1. Import the repo into Vercel and keep main as the Production Branch.
2. Add your shared secrets to the correct Vercel environments:
   • Production: real production values, including NEXT_PUBLIC_APP_URL=https://your-domain.com
   • Preview: shared preview values for non-production branches
   • Development: local vercel dev / vercel env pull usage
3. For staging, add branch-specific Preview overrides only for values that should differ from other preview branches.
   • Example: set NEXT_PUBLIC_APP_URL=https://staging.your-domain.com only for the staging preview branch if you want a stable staging URL
4. If you want a stable staging domain, assign that domain to the staging Git branch in Vercel.
5. Let feature/* branches use the default generated Preview URLs unless you have a specific reason to override them.

Repo behavior

• Production deploys use NEXT_PUBLIC_APP_URL when you set it.
• Preview deploys now automatically fall back to the active Vercel branch/deployment URL when NEXT_PUBLIC_APP_URL is not set for Preview.
• That means staging and feature/* previews no longer fall back to http://localhost:3000 for metadata and generated portfolio links.

Support and contribute

DevFrame is free and open-source. The easiest ways to support the project are:

• Star the repository: https://github.com/RegieSanJuan/DevFrame
• Report bugs with clear reproduction steps.
• Suggest features through GitHub Issues or Discussions.
• Contribute code, docs, and templates. Start with CONTRIBUTING.md.
• Support development through the GoTyme InstaPay or GCash QR codes on /support.

Donations are optional and help cover hosting, tools, and continued development. There is no Ko-fi, PayPal, Patreon, or payment API integration in this repo.

How persistence works

• If Clerk and Supabase are configured, portfolio submissions are saved to Supabase.
• If Supabase is missing, the builder still works in preview mode using a secure cookie so you can keep designing the experience locally.
• Public portfolio pages always try Supabase first, then fall back to local seeded examples and preview mode.

Suggested next steps

• Add image upload flows with Supabase Storage
• Add more template variants
• Add a custom domain workflow
• Add an editor for multiple projects, testimonials, and blog posts
• Improve contribution guides and community templates

Customizing & Adding Templates

DevFrame uses a modular template system. Each template is a standalone React component registered in a central registry.

How to customize a template

1. Specific Template: Edit the file in src/templates/. For example, to change the "Nova" template, edit src/templates/nova/index.tsx.
2. Shared Components: Common elements like LinkPill or SkillBadge are located in src/templates/base-components.tsx. Changing these will update all templates simultaneously.
3. Global Styles: Core design tokens (colors, fonts) are defined as CSS variables in src/app/globals.css.

How to add a new template

1. Create the component: Create a new file (e.g., src/templates/my-new-template.tsx).
2. Register it: Call registerTemplate("my-slug", MyComponent) at the bottom of your file.
3. Import it: Add an import for your new template in src/templates/index.ts.
4. Update Catalog: Add your template metadata (slug, name, tagline, etc.) to src/lib/template-catalog.ts so it appearing in the builder.
5. (Optional) Add Seed Data: Add a sample portfolio for your template in src/lib/portfolio-storage.ts to enable instant previews.

Template Architecture

• src/templates/registry.ts: The central registry mapping slugs to components.
• src/components/portfolio-renderer.tsx: The main renderer that dynamically loads the correct template.