Next.js Admin Panel Documentation

Choose the task that matches your goal. To add the editor to an existing Next.js website, start with the CLI installation, choose manual wiring or the codemod, then connect your database and environment. To host this project’s own website and shared AI endpoint, follow the separate Vercel and operator instructions.

Your layout and application logic stay in code. Editable defaults live in editable-panel.config.json; published overrides live in your own Supabase project. The public demo stores changes in browser memory and resets on reload.

The CLI needs Node.js 22.13 or newer; this repository uses Node 24.x. Supported targets are TypeScript App Router projects on Next.js 15/16 with React 19. The @/* alias must point to ./* or ./src/*. Use one App Router root: app or src/app. Installation builds are checked on Next.js 16.2.1; verify other supported versions in your project.

The installed editor uses scoped CSS and needs neither Tailwind nor shadcn. The installer adds missing Supabase, sharp and server-only dependencies. Pages Router, JavaScript-only projects, custom basePath and static export are outside the supported scope.

Run the following commands from the root of your existing Next.js project. The first command previews the installation; the second applies manual mode. This website-hosted archive does not need an npm account or permanent global installation. It is generated during this project’s Vercel build.

Manual mode preserves existing pages. Choose --content codemod instead if you want supported static TSX page text moved into config automatically. Interactive init asks which mode you want; scripts and JSON output default to manual unless you specify otherwise.

The multipage preset creates /panel-example, /panel-example/about and /panel-example/contact. The minimal preset creates only /panel-example. After installation, configure your own database and environment before using the real editor. No Supabase account, SQL execution or deployment is performed by init.

Create or choose your own Supabase project. Back up existing data, open its SQL Editor, paste the generated supabase/migrations/202610280001_panel_security.sql and run it. Migration 001 creates or upgrades the content table, timestamp trigger and login-throttle function. It is also required when upgrading an older installation.

The migration preserves content values and takes ownership of policies on the dedicated content table. If another application uses that table, review the changes first. Existing image bucket settings and policies are preserved and need separate inspection.

A service-role Data API key cannot execute SQL migrations. Setting env values or deploying on Vercel does not run SQL. Use the SQL Editor or an authorised database migration connection.

In an installed application, copy values from .env.panel.example into .env.local. For this repository, use .env.example. Set the same server variables in Vercel before production deployment. Never commit the files containing real values. Shell variables take precedence over .env.local, which takes precedence over .env in the CLI.

ADMIN_PASSWORD must contain at least 16 characters; use a long random password. PANEL_SITE_URL must be your exact production origin, including https://. Locally use http://localhost:3000. Changing ADMIN_PASSWORD revokes all signed sessions. ADMIN_SESSION_SECRET is optional. NEXT_PUBLIC identifies browser-safe values; never add that prefix to a service-role key, password, session secret or Gemini key.

Choose one way to connect content. In manual mode, register the page path, section IDs and fields in editable-panel.config.json, then read the values in a Server Component and pass them to the client sections that need preview. The code below shows the reader and preview hook. Keep authentication, database queries and other server logic on the server.

The preset’s home page initially points to /panel-example. If you connect your actual homepage manually, change its path to /, or register a separate page. Section IDs should match DOM IDs so the editor can scroll the preview. Run elp pages list to see the actual IDs: codemod-generated IDs can be home-2 or contact-2 to avoid existing preset IDs.

For automatic migration, use the codemod commands below. It scans default-function page.tsx files under app or src/app. Static text and supported alt/title/placeholder/aria-label/link/image attributes receive keys, labels, types and defaults. Existing section IDs group fields.

Simple client pages without props or extra exports receive a server wrapper and preview view. Server pages receive published values through the reader; unsaved preview still needs a client boundary. Imported components, callbacks, dynamic routes, dynamic expressions and unsupported exports remain for manual work.

If you render Supabase uploads with next/image, allow your exact public-images host/path in your Next config. The installer does not rewrite that config. Plain image previews do not need the Next image allowlist.

The configuration is versioned JSON; it is read by the website, editor and CLI. Every field has a globally unique key, label, supported type, default string and maxLength (1–20000). Page and section IDs use lowercase letters, digits and hyphens. Paths are root-relative routes. Duplicate keys/IDs, executable URLs and unsupported definitions fail validation.

Use namespaced keys such as about.title in new projects. Existing hero_title and other legacy keys remain supported in this repository. A page whose ID is global contributes shared fields to every page read. A config entry does not create a Next.js route. Default values are a fallback, not a seed operation that overwrites the database.

Select a page in /admin to change the visible fields and preview route together. Selection is remembered in the URL. Field search matches labels and keys. Switching pages or leaving with unsaved edits asks for confirmation. Add the route in Next.js and its page definition in config to support another existing page.

Text drafts preview immediately in integrated client sections. Save changes publishes a validated batch; failures retain the draft. Reset immediately removes one stored override after confirmation. Uploads are server-checked and create an immutable image URL, then Save changes publishes that URL. Discarding after upload may leave an orphaned file; cleanup is manual to avoid breaking backups.

Already-open visitor pages need refresh to see later publications. There is no visitor realtime subscription, individual editor role system or conflict resolution: simultaneous edits are last-write-wins. The /demo sandbox uses browser-only state and resets on reload.

The editor keeps its original preview-left, field-cards-right layout. Click a value or Edit to open its text field. The field Save action and the Save changes toolbar action both publish the current pending batch. Use the page selector to switch routes; on mobile, Edit/Preview switches the visible pane.

The package is named editable-landing-panel; its executable is elp. npx --package=<tarball> elp runs without a permanent installation. All commands support --cwd and --json. No-output-file overwrite is allowed. --dry-run prevents file/database writes, but an explicit ai --dry-run still calls the provider to generate its preview.

Exit code 0 means success; 1 means failure. init returns 2 if installation completed but an optional codemod or AI step failed. AI is skipped if the codemod failed. In that case the installed editor remains usable and AI can be retried separately. JSON output includes the installation result and AI result as one document.

An import can contain {"values":{"home.title":"New title"}} or a plain key/value object. The entire batch is validated before changes. --defaults changes only the matching default strings in editable-panel.config.json. --remote makes one atomic upsert and does not delete unspecified keys. Choose exactly one target: --defaults, --remote or --out.

Database overrides take precedence over local defaults. Updating a default does not replace a client’s saved value; reset that field in the editor or use an explicit remote import if you want to replace it. Export --remote merges defaults with stored values; it is a portable snapshot, not an exact override-only database backup. Make a database backup separately before changing permissions or migrations.

AI is optional and separate from the codemod. A normal installation and local text migration need no Gemini account or key. Gemini uses a brief plus the selected registered text fields to prepare new copy. Create a UTF-8 file such as brief.txt with your description, audience and tone, then run the command below.

Without a local GEMINI_API_KEY, the CLI uses the operator’s shared endpoint if enabled and available. Your own GEMINI_API_KEY takes precedence and is sent directly to Google, never to the shared operator. GEMINI_MODEL defaults to gemini-3.5-flash-lite. ELP_AI_URL or --ai-url can select another trusted shared deployment.

When --page is omitted, AI uses the first configured page plus shared text fields. Run elp pages list before choosing an ID, especially after a codemod. Requests support 1–64 text fields; images are excluded. The CLI does not upload source files or database credentials.

Shared application budgets are 3 requests per client IP and 20 total per UTC day; provider limits can be lower. A shared-service failure prints own-key guidance. The CLI never silently switches to a paid account. Check Google’s current model availability, pricing and data-use terms before sending confidential material.

Open Google AI Studio, create/select your project and obtain an API key for the Gemini Developer API. Confirm the model is available and the project is on the intended free tier; a key itself does not guarantee free unlimited usage. Add the key to your target project’s .env.local (not .env.panel.example, not NEXT_PUBLIC). Keep it out of Git. Run the same CLI command again: it automatically uses your key instead of the shared service.

The brief and selected text-field definitions/defaults are transmitted for generation. The CLI does not upload source files, Supabase keys or admin passwords. In shared mode the operator’s server processes the brief before forwarding to Google. Review provider data-use terms before submitting client confidential material. Do not put secrets into a brief.

This section is for hosting this repository’s own website. Import it into Vercel with the Next.js preset and Node 24. Keep the repository root as the project root and use pnpm build. That command creates the public CLI archive before building the website; bare next build omits the packaging step.

Apply migration 001 to the chosen Supabase database before using the admin. If you enable shared AI, also apply migration 002 and add its server settings below. Set the env values in the relevant Vercel environment and redeploy. SQL is not run automatically.

After deployment, test /admin login/save/reset/upload, /docs and the CLI download. If shared AI is enabled, test generation with and without a local user key. People installing the CLI use their own website/database; they do not gain editing access to this deployment.

The shared endpoint is POST /api/editable-panel/assist. It accepts bounded JSON containing brief and text-field definitions. It cannot query website content, accept arbitrary Gemini models from callers, forward your API key, use tools, execute code or publish generated text. Server-side model/key settings control provider access. It is public intentionally for CLI clients; CORS/Origin checks are not bot authentication.

Enable it only after migration 002. The function atomically reserves the per-IP and global daily budgets in Supabase before contacting Google; failures consume reservations too. Quota state is shared by all Vercel instances. Raw IPs are HMAC-hashed with PANEL_AI_RATE_SECRET, and the function trusts Vercel’s platform IP header. Missing protection or trusted IP fails closed. Outside Vercel, only enable PANEL_TRUST_PROXY behind a proxy that overwrites forwarded headers.

The global cap limits successful generation reservations but does not prevent someone from exhausting the shared allowance or sending many rejected requests. Use Vercel Firewall/request limits and provider billing controls appropriate to public traffic. On a paid Gemini project, a small number of requests can still cost money: application limits do not make a paid API free. Disable immediately with PANEL_AI_ENABLED=false if necessary.

PANEL_AI_RATE_SECRET is a private random server secret, not a password for users and not a Gemini credential. Add it only in Vercel Environment Variables for the shared-service deployment (Production, and Preview only if you enable the service there). It signs HMAC fingerprints of client IPs before the quota function records them, so the database stores no raw IPs. Use a cryptographically random value of at least 32 characters and keep it stable. Rotating it changes per-client fingerprints; the global daily cap remains. Generate 32 random bytes as 64 hex characters with the command below.

You do not have to create an npm account for the website-hosted download path. pnpm build creates public/downloads/editable-landing-panel-0.3.1.tgz from a fixed list of runtime assets, code and documentation. Vercel serves it from your domain. npx --package=<HTTPS download> elp init is a real installation command, not an example of an already-published registry package.

For the shorter npx editable-landing-panel@0.3.1 init command, an owner must separately publish packages/cli to npm with a permitted package name and authenticated npm account. Deploying on Vercel does not publish to npm. The project executable is elp in either case. The build bakes your configured HTTPS PANEL_SITE_URL into the downloadable CLI’s shared endpoint. After changing domains, rebuild and re-download; already downloaded CLI copies can override the URL with ELP_AI_URL or --ai-url.

The website editor uses a same-origin signed cookie, not the old x-admin-password header. Session cookies are scoped to /api/editable-panel and never contain the password. Mutations require the configured Origin. Content reads for the editor require a session; public pages use the server reader and public read-only database access. All API responses disable caching.

Legacy /api/login, /api/content, /api/get-content and /api/upload endpoints are removed in this version. Custom clients using them must migrate. The shared AI endpoint is separate: it is public with database-backed budgets and does not grant content-editing access.

The baseline migration explicitly enables RLS and revokes public write privileges, including TRUNCATE. Run verify.sql and review actual storage policies: an existing bucket’s public/private flag alone does not prove safe write permissions. All rows in content are public published values; never store credentials or drafts there.

Use HTTPS, a unique long password and exact PANEL_SITE_URL. Login throttling is database-backed and fails closed if unavailable. The default login bucket is shared across clients; opt into trusted-IP handling only behind an overwriting proxy. This is one shared administrator, not an enterprise access-control system. No per-user roles, content revisions, conflict detection or individual-token revocation are provided. Logout removes this browser’s cookie; password rotation revokes every token. An already copied valid token otherwise lasts until its eight-hour expiry.

A successful local build/test is not certification of your live database, Vercel firewall or a penetration test. Configure backups, platform limits and monitoring before opening a public shared service.

Optional Google Analytics needs NEXT_PUBLIC_GA_ID and explicit visitor acceptance in the cookie banner. Scripts stay unloaded until acceptance; refusal is remembered for up to 180 days. Cookie settings allows changing or withdrawing consent. Admin and embedded preview pages do not initialize analytics. /privacy explains essential storage, providers and optional AI processing; fork operators must adapt the operator/contact details and review their own retention settings. Geist fonts are self-hosted and require no Google Fonts connection.

Run doctor after setting environment and applying SQL. Public pages log a warning and fall back to config on database read failures; the editor reports errors rather than pretending a failed read succeeded. Remote diagnostics inspect content and bucket metadata and make an empty anonymous upsert probe; no rows are inserted, but SQL inspection is still needed to prove every permission.

Login 503: check migration 001, database access and a password of at least 16 characters. Production Origin 403/503: check PANEL_SITE_URL against the exact scheme/host you use. Shared AI 503: check enable flag, key, rate secret, migration 002 and trusted platform IP. Shared AI 429: use your own key or retry after the daily window; increasing account limits is not automatically free. init conflicts: inspect the reported existing path/route rather than forcing an overwrite. Upload errors: check bucket permissions and supported JPEG/PNG/WebP/AVIF size ≤5 MB / 40 MP.

Concurrent editors are last-write-wins. Export before bulk changes, inspect orphaned uploads manually, and do not remove files still referenced by backups.

Vercel install error ERR_PNPM_IGNORED_BUILDS: pnpm 11 uses allowBuilds in pnpm-workspace.yaml; legacy ignoredBuiltDependencies is no longer honored. Keep the committed policy, which approves reviewed native package versions and disables the unused msw postinstall. After dependency upgrades, review any newly reported package/version before updating that policy. Do not disable strict build checks or enable all dependency scripts. This install failure does not require reapplying SQL migrations or replacing environment keys. The repository pins Node 24.x; the standalone CLI supports Node >=22.13.