Spike-NextJS-PRO-Template

👋 Introduction

Flexy is a sleek, professional admin dashboard template built with Next.js, Material UI (MUI), and TypeScript. Designed for performance, flexibility, and ease of customization, Flexy offers a powerful foundation for building modern, scalable web applications with minimal effort.

Whether you're creating admin panels, CRMs, SaaS dashboards, or internal tools, Flexy helps you move fast with a clean Material Design aesthetic, reusable components, and a flexible layout system.

Powered by the modern web stack of Next.js, MUI, and TypeScript, Flexy delivers fast performance, strong typing, and a smooth developer experience—so you can focus on building features, not boilerplate.

🔑 Key Features

• Responsive Design
  Delivers a seamless experience across desktops, tablets, and mobile devices with MUI's responsive grid system.

• Material UI Components
  Built entirely with MUI (Material UI)—customizable, accessible components that follow Google's Material Design guidelines.

• Pre-designed Pages
  Comes with essential pages like dashboards, authentication screens, user profiles, error pages, and more to help you start fast.

• ApexCharts Integration
  Interactive, customizable charts powered by ApexCharts for clear and effective data visualization.

• Optimized for Performance
  Lightning-fast page loads, image optimization, and best practices built in using Next.js features like dynamic imports and SSR/SSG.

• Developer Friendly
  Clean folder structure, modular codebase, and simple theme customization make it easy to build and scale.

---

🛠️ Notable Libraries and Tools

Library / Tool	Description
Next.js	A powerful React framework for building server-rendered and statically generated web applications with routing, SSR, and API routes.
Material UI (MUI)	A comprehensive UI component library based on Google's Material Design system, providing responsive, accessible, and highly customizable components.
ApexCharts	A modern charting library used to create interactive and customizable charts, ideal for visualizing dashboard data.
Emotion	A performant and flexible CSS-in-JS library used by MUI for styling components with dynamic and scoped styles.
MUI Icons	A collection of Material Design icons used throughout the dashboard for consistent, scalable UI elements.

---

Implementation

Guide for AI coding agents working from the WrapPixel Spike Next.js UI template.

This README is written so tools like Augment, Claude Code, or similar coding agents can understand:

• how the template is organized
• where to make changes safely
• how to customize theme, layout, navigation, and branding
• how to extend the template without fighting the existing structure
• how to use this repo as a shared UI base that can be pulled into many different product repos

Primary upstream documentation: WrapPixel Spike Next.js docs
https://wrappixel.github.io/premium-documentation-wp/nextjs/spike/index.html

---

Purpose

Use this repository as a shared UI foundation for multiple Next.js admin applications based on the Spike template.

An AI coding agent should treat this repo as:

• a UI base repo, not a finished product
• a reusable admin shell for many apps
• a theme + layout + navigation starter that should be imported into app repos and then customized per project
• a shared frontend baseline that should stay relatively clean and generic

This repository should contain the reusable pieces that many projects benefit from, such as:

• layout shell
• theme configuration
• sidebar/header structure
• shared page primitives
• auth-ready app shell
• reusable tables, cards, forms, empty states, and loading states

Project-specific repos should then layer their own:

• branding
• route structure
• business features
• API clients
• auth provider details
• domain-specific components

---

Core rule for AI agents

When working from this repo, an AI agent should separate changes into two categories.

Base-repo changes

Put changes here only if they are broadly reusable across many apps:

• theme system improvements
• layout fixes
• shared navigation patterns
• generic shell components
• reusable table/form/page primitives
• accessibility and responsiveness fixes
• common auth shell plumbing

Project-repo changes

Put changes in the consuming project if they are specific to one product:

• logos and brand colors
• product navigation
• domain pages
• API integrations
• customer-specific workflows
• role models, permissions, product language
• product-specific dashboards

If unsure, default to keeping the base repo generic and moving app-specific logic into the consuming repo.

---

What the upstream template provides

The upstream Spike docs show a Next.js + MUI admin template with:

• package-oriented app variants
• dashboard layouts
• configurable theme settings
• light/dark support
• RTL support
• menu-driven routing
• logo customization
• authentication wiring points
• reusable dashboard/app/chart/form/table/widget scaffolding

For implementation details, the agent should inspect the local repo first, then use the upstream docs only as a reference for intent and expected structure.

---

Recommended repository model

This repo should live in its own dedicated repository, for example:

ui-base-spike/

Then each product repo can consume it, for example:

inventory-portal/
admin-licensing/
deployment-console/
customer-ops-ui/

The base repo should avoid becoming tightly coupled to any one product.

---

Best ways to pull this UI base into different projects

There is no single perfect method. The right choice depends on whether you want easy syncing, simple behavior, or maximum per-project freedom.

Option 1: Git subtree copy-in (recommended for most teams)

Use this base repo as a subtree copied into each project repo, usually into a folder like:

frontend/
ui/
apps/web/

Why this is usually the best choice:

• easy to understand
• no special runtime dependency model
• consuming repo fully owns the files after pull-in
• updates from the base repo can still be merged later
• avoids submodule confusion

Example shape:

inventory-portal/
  apps/
    web/
      ...Spike-based UI files...

Example subtree flow:

git remote add ui-base <BASE_REPO_URL>
git subtree add --prefix apps/web ui-base main --squash

Later update:

git subtree pull --prefix apps/web ui-base main --squash

Option 2: Git submodule (good if you want strict separation)

Use a submodule if you want the UI base to remain a separately versioned repo inside each project.

Example:

inventory-portal/
  external/
    ui-base/

Pros:

• clear separation
• easy to track exact base version
• good if many repos share the same unmodified base

Cons:

• developers often mishandle submodules
• customization inside the consuming repo is more awkward
• easy to break onboarding if submodules are not initialized

Use this only if your team is already comfortable with submodules.

Option 3: Internal starter/template repo (good for one-time bootstrap)

Use this repo as the source for creating new projects, then let each repo diverge freely.

Good when:

• each project will become heavily customized
• you do not expect frequent sync-back from the base repo
• mostly needs a strong starting point, not long-term inheritance

This is easiest operationally, but weakest for centralized updates.

Option 4: Internal package/workspace model (best for shared components, not full app shells)

Convert only the reusable UI parts into an internal package, such as:

@company/ui-shell

This is excellent for:

• reusable components
• theme providers
• layout primitives
• design system pieces

It is less ideal for an entire routed admin app template unless you deliberately architect for that.

---

Recommendation for this repo

For this Spike-based setup, the most practical model is usually:

1. keep this repo as a dedicated UI base repo
2. pull it into a project repo using git subtree
3. reserve the base repo for reusable shell improvements
4. make project branding and product pages in the consuming repo

That gives the best balance of:

• shared improvements
• easy project customization
• simple AI-agent behavior
• less git complexity

---

How should pull this into a new project

When asked to use this UI base in another repo, should follow this workflow.

Preferred workflow: subtree import

1. Clone or open the target project repo.
2. Decide where the frontend should live.
3. Add this UI base repo as a temporary git remote.
4. Pull the base repo into the target folder with git subtree.
5. Rename or adapt only project-specific parts.
6. Keep a note in the consuming repo README explaining that the UI shell came from this base repo.

Example commands:

git remote add ui-base <BASE_REPO_URL>
git subtree add --prefix apps/web ui-base main --squash

If the project already has files in that folder, should either:

• import into a new folder such as apps/admin, or
• carefully merge only after inspecting conflicts

If is instructed to use submodules instead

Example:

git submodule add <BASE_REPO_URL> external/ui-base
git submodule update --init --recursive

Then should either:

• build from that submodule directly, or
• copy the needed app shell into the project if per-project customization is required

If is instructed to use this as a one-time starter should:

1. copy the repo contents into the target project frontend folder
2. remove any leftover generic placeholder branding
3. immediately establish project-specific config files
4. record the original source repo in documentation

---

How should customize the imported UI per project

After pulling the base into a project repo, should treat the imported code as a shell to adapt in a controlled way.

First-pass customization steps

1. Replace branding and logos.
2. Set project theme defaults.
3. Clean the sidebar to match the product.
4. Remove demo pages from navigation.
5. Create the initial route structure for the product.
6. Connect auth.
7. Connect APIs.
8. Add project-specific shared components.

Keep these generic in the base repo when possible

• page containers
• section headers
• data table wrappers
• filter bars
• drawer/modal patterns
• empty states
• loading skeletons
• theme tokens
• responsive layout behavior

Move these into the project repo

• product logo assets
• product menu items
• product feature pages
• product API client code
• product auth provider details
• product terminology and copy

---

Ideal structure for a consuming project

A consuming project should usually look something like this after import:

project-repo/
  apps/
    web/
      src/
        app/
        components/
        public/
        utils/
      package.json
  backend/
  docs/
  README.md

If the project has more than one frontend, this base can live at:

apps/admin/

or:

frontend/admin/

The exact folder name is less important than keeping it consistent.

---

Template structure to understand first

The upstream docs show a package-oriented layout with a main working app under something like packages/main, and app code primarily under folders like:

• src/app
• src/components
• src/api
• src/auth
• src/contextapi
• public
• utils

The dashboard layout pages are typically under src/app/(DashboardLayout).

Important directories

packages/
  main/
    public/
    src/
      app/
        (DashboardLayout)/
          apps/
          charts/
          components/
          dashboards/
          forms/
          icons/
          layout/
          sample-page/
          tables/
          theme-pages/
          types/
          ui-components/
          utilities/
          widgets/
          layout.tsx
          loading.tsx
          page.tsx
      api/
      auth/
      components/
      contextapi/
      landingpage/
      global.css
      layout.tsx
      loading.tsx
    utils/
    next.config.js
    package.json
    tsconfig.json

How an AI agent should interpret this

• src/app/(DashboardLayout) = main app pages using the shared dashboard shell
• src/app/.../layout = header, sidebar, wrappers, and shell structure
• src/components = reusable presentation components
• src/api = mock/example or API helper areas depending on the repo
• src/auth = auth-related flows and wiring
• public/ = static images and logos
• utils/ = shared utilities and theme helpers

---

Quick start for agents

The agent should inspect the actual repo first, but standard startup is typically:

npm install
npm run dev
npm run build

If the repo is monorepo-based, the agent should first determine which package is the active frontend package.

---

Rules for AI coding agents

1. Preserve the layout system

Do not replace the dashboard layout architecture unless explicitly asked.

2. Reuse before rebuilding

Before creating a new card, table wrapper, page header, modal, or form shell:

• search for an existing equivalent in src/components
• search nearby dashboard pages for an existing pattern
• copy and adapt the local pattern

3. Keep styling consistent

Prefer the existing MUI and theme flow already used by Spike.

4. Put business logic in the project layer

Avoid filling reusable template internals with project-specific business logic.

5. Avoid broad renames

Do not rename major folders or shared layout files unless explicitly asked.

6. Keep routes and menu items synchronized

If a new page should appear in navigation, update both:

• the app route
• the sidebar/menu config

---

How to add new pages

When adding a new page:

1. create the route under the correct dashboard segment
2. add a page.tsx using the existing nearby structure
3. reuse existing layout wrappers
4. if the page belongs in nav, update the menu config
5. keep route naming clean and consistent

Example pattern:

src/app/(DashboardLayout)/reports/usage/page.tsx

Then add the matching sidebar item in the local menu configuration.

---

Theme customization

The Spike docs indicate that theme customization is driven centrally through configuration/context files, often involving settings such as:

• activeTheme
• activeMode
• activeDir
• SidebarWidth
• TopbarHeight
• isLayout
• isCollapse
• isHorizontal
• borderRadius

Agent guidance

Before editing component-level styles, check whether the requested change should instead be done centrally.

Examples:

• dark mode default -> change activeMode
• RTL default -> change activeDir
• boxed vs full layout -> change isLayout
• default brand theme -> change activeTheme
• roundness -> change borderRadius

Do not scatter one-off hardcoded styling values across many components unless necessary.

---

Branding and logo changes

The docs indicate that logo changes are made in the shared logo component and static assets under public.

Agent procedure

When updating branding:

1. place logo assets in the appropriate public path
2. update the shared logo component
3. preserve light/dark variants if used
4. preserve RTL variants if used
5. keep dimensions aligned with topbar/sidebar sizing

---

Sidebar and navigation customization

When customizing navigation:

• group related items together
• keep naming concise
• remove demo links that are not relevant
• align navigation to the project information architecture
• do not leave generic template sections in production nav unless they are actually used

For most consuming projects, should remove template-only items such as demo dashboards, sample pages, and placeholder widgets.

---

Authentication customization

The Spike docs show auth wiring points that can be adapted or replaced.

Agent guidance

When implementing auth:

1. determine whether the project keeps the default auth approach or replaces it
2. keep provider wiring centralized
3. update protected routes, login/logout flows, and session logic together
4. avoid mixing multiple unfinished auth systems

---

How to keep the base repo healthy

The base repo should not become a dumping ground for one product's needs.

Changes that belong in this base repo

• layout bug fixes
• shell responsiveness fixes
• generic accessibility improvements
• shared table/filter/page primitives
• reusable theme improvements
• common loading and empty states
• generic auth-shell improvements

Changes that should usually stay out of the base repo

• customer-specific dashboards
• project-specific icons and logos
• one-off API clients
• product-specific workflow components
• business-specific role models
• domain-specific copy everywhere

---

Suggested branch and sync model

A practical model is:

• main in this repo = stable reusable UI base
• each project repo imports from this repo
• project repos customize locally
• useful generic improvements can be promoted back into this base repo later

If an agent makes a generally reusable improvement in a project repo, it should consider whether that change should be backported into this base repo.

---

Suggested repository-specific section to fill in

An agent should update this section after inspecting the actual local repo.

Active app package

• <fill in>

Main dashboard layout path

• <fill in>

Sidebar menu config path

• <fill in>

Theme/customizer config path

• <fill in>

Logo component path

• <fill in>

Auth provider path

• <fill in>

API client path

• <fill in>

---

Summary for AI tools

If you are an AI coding agent working with this repository, optimize for:

• minimal-disruption implementation
• reuse of the existing Spike layout and component patterns
• centralized customization through config/context
• clean route + sidebar consistency
• strong branding replacement
• gradual removal of demo-only content
• keeping the base repo generic
• moving product-specific logic into the consuming project repo

Treat this repository as a shared UI shell that can be pulled into multiple projects, not as a single product app.