WeBase Admin Template

WeBase Admin Template is an independent Next.js App Router admin scaffold for building operational management consoles. It includes a polished dark-first login experience, an admin shell, dashboard metrics, local mock CRUD flows, role/menu governance, global search, and system settings.

Quick start

npm ci
cp .env.example .env.local
npm run dev

Open http://localhost:3000, then sign in with the mock credentials below.

Template initialization

The repository ships with WeBase branding in repository metadata and app metadata. To preview a conservative first-pass rename, run:

npm run init:template -- --name "Acme Admin" --short-name "Acme" --description "A production-ready Next.js admin template for Acme operations." --github-owner acme --github-repo admin-console

Add --write to apply the changes after reviewing the preview output.

The script is intentionally conservative:

• It updates only package.json, README.md, public/manifest.json, and src/app/layout.tsx.
• It skips fields that no longer match the shipped WeBase defaults instead of overwriting customized values.
• If you change package.json name, refresh the lockfile metadata with npm install --package-lock-only.

Demo

Run the template locally with npm run dev, or use the GitHub Pages build after it has deployed from main: https://weopen.github.io/WeBase/.

The demo runs in mock mode by default, so it is safe to explore CRUD flows, permissions, navigation, audit logs, settings, and /system/health without a backend. For demo routes, screenshot guidance, and deployment notes, see Demo guide.

Screenshots

Screenshots are intentionally not checked in until they are captured from a verified build. Recommended captures for a release are the login page, dashboard, user management, role permissions, and system health views. Store approved images under public/screenshots/ and reference them here after verifying the files render in GitHub and the Pages site.

Tech stack

• Next.js 16 App Router
• React 19
• TypeScript 6
• Tailwind CSS 4
• Zustand for lightweight client state
• next-themes for theme handling
• lucide-react for icons
• ESLint 9 with Next.js configuration

Routes

Route	Purpose
/	Redirect entry page for the app shell
/login	Demo login page
/dashboard	Chart-first admin overview and operational metrics
/system/users	Mock user management with filtering and CRUD-style interactions
/system/roles	Role management and permission assignment
/system/menus	Menu management for the admin navigation tree
/system/audit-logs	Audit log review for admin operations
/system/notifications	Notification center and delivery state management
/system/sessions	Active session and device risk management
/system/components	Local design-system component showcase
/system/health	Runtime mode, backend readiness, and production smoke status
/system/settings	System profile, theme, session, and notification settings
/account/profile	Current user profile, preferences, and security summary

Mock credentials

The login form is prefilled with demo credentials:

• Username: admin
• Password: admin123

The current mock adapter accepts the displayed admin / admin123 credentials, then returns a local demo session. HTTP mode delegates credential validation to the backend.

Environment variables

Copy .env.example to .env.local and adjust as needed:

Variable	Purpose
NEXT_PUBLIC_API_MODE	mock for local demos, http for a real backend
NEXT_PUBLIC_API_BASE_URL	Backend base URL when HTTP mode is enabled
NEXT_PUBLIC_API_TIMEOUT_MS	Default HTTP timeout in milliseconds

Development commands

npm run dev
npm run verify
npm run lint
npm run smoke:e2e
npm run smoke:template
npm run smoke:production
npm run build
npm run start

• npm run dev starts the local development server.
• npm run verify runs the full CI gate: standards lint, production smoke suite, TypeScript, and production build.
• npm run lint runs ESLint across the project.
• npm run smoke:e2e verifies that the documented browser/E2E and backend integration workflows remain linked and reviewable without adding a browser test dependency.
• npm run smoke:template verifies template extension contracts such as route registry, RBAC, API adapter, form validation, docs, status pages, theme tokens, and dashboard chart loading.
• npm run smoke:production runs the production readiness smoke suite, including i18n, auth, API, permissions, CRUD, audit, accessibility, template, and /system/health checks.
• npm run build creates a production Next.js build and verifies buildable routes.
• npm run start serves the production build after npm run build.

CI and automation

GitHub Actions runs CI for every pull request and for every push to main. The Pages deployment workflow runs only after pushes to main.

To verify workflow status in GitHub, open the pull request or commit and inspect the status checks section. Use the Actions tab when you need job logs for CI or Deploy to GitHub Pages.

Release verification

Before connecting a real backend or deploying a release, run:

npm run verify

Then open /system/health to confirm API mode, backend/mock status, frontend version, build target, and operational indicators.

Treat the template as release-ready only after npm run verify passes on the release candidate and the GitHub CI workflow is green for the target commit. For the full release checklist, changelog alignment, and tag guidance, see Release checklist.

Production security boundary

Frontend RBAC, route guards, mock sessions, and permission-aware UI controls are template conveniences. A production backend must enforce authentication, authorization, data-scope checks, session expiry, audit logging, CSRF protection where applicable, and rate limiting. Do not treat hidden buttons or client route redirects as security controls.

Dependency audit note

PostCSS is pinned through npm overrides so transitive consumers use a patched release. Track upstream Next.js releases and remove the override once Next depends on a patched PostCSS version directly.

Template extension docs

• Add an admin module
• API adapter guide
• Backend integration contract
• Accessibility maturity
• Demo guide
• Permissions and RBAC
• Contributing
• Security policy
• Code of conduct
• Changelog
• Release checklist
• Admin template hardening plan

API adapter note

The app is wired through src/lib/api/client.ts, which delegates to the in-memory mock adapter in src/lib/api/mock-adapter.ts by default and can switch to src/lib/api/http-adapter.ts with NEXT_PUBLIC_API_MODE=http. Feature services under src/lib/services/ call this client instead of importing mock data directly, so replacing the mock layer with real HTTP requests should be limited to the API client/adapter boundary while preserving service contracts.

Mock data is stored in memory in src/lib/api/mock-data.ts; create, update, and delete interactions are for the current browser session only and are not persisted.

License

MIT