@infuro/cms-core 1.0.5 → 1.0.7

package/README.md

@@ -1,34 +1,43 @@
 # @infuro/cms-core
 
-A headless CMS framework built on Next.js and TypeORM. Provides a ready-to-use admin panel, CRUD API layer, authentication, plugin system, and UI components — so you only write what's unique to your website.
+A headless CMS framework built on Next.js and TypeORM. It provides a ready-to-use admin panel, CRUD API layer, authentication, plugin system, and UI components — so you only write what's unique to your website.
 
-## Architecture
+## Overview
+
+You don't set up or clone core in each website. Install the published package and run the init command to scaffold a new site.
+
+**Typical workflow for a new site:**
+
+1. Create a Next.js app (TypeScript, Tailwind, App Router, `src` directory):  
+   `npx create-next-app@latest my-site --typescript --tailwind --app --src-dir`
+2. From the project root, run:  
+   `npx @infuro/cms-core init`
+3. Copy `.env.example` to `.env`, set `DATABASE_URL`, `NEXTAUTH_SECRET`, `NEXTAUTH_URL`, then run `npm run seed` (or migrations) and `npm run dev`.
+
+Init creates all required files (data-source, auth-helpers, cms, API routes, admin layout and page, middleware, providers, seed, migration runner, default theme, basic home and contact pages), and can patch `next.config`, `tailwind.config`, layout, and `package.json` and install dependencies. Use `--force` to overwrite existing files, `--dry-run` to see what would be created, `--no-deps` to skip npm install, `--no-patch-config` to skip config changes.
+
+**Manual setup (if you prefer not to use init):** Install from npm (`npm install @infuro/cms-core typeorm reflect-metadata bcryptjs next-auth next-themes sonner` and `npm install -D @types/node`), then follow the step-by-step setup below. For local development of core itself, use `"@infuro/cms-core": "file:../core"` in the site's package.json.
+
+## Project structure (your site after setup)
 
 ```
-core/                         # This package
-├── src/
-│   ├── entities/             # TypeORM entities (User, Blog, Form, etc.)
-│   ├── api/                  # API handlers (CRUD, auth, CMS-specific)
-│   ├── auth/                 # NextAuth config, middleware, helpers
-│   ├── admin/                # Admin panel (layout, pages, page resolver)
-│   ├── plugins/              # Plugin system (email, storage, analytics, ERP, etc.)
-│   ├── components/           # Shared UI (shadcn/ui + Admin components)
-│   ├── hooks/                # React hooks (analytics, mobile, plugin)
-│   └── lib/                  # Utilities (cn, etc.)
-
-your-website/                 # Your Next.js app
+your-website/
 ├── src/
 │   ├── app/
-│   │   ├── admin/            # 2 files: layout.tsx + [[...slug]]/page.tsx
+│   │   ├── admin/            # layout.tsx + [[...slug]]/page.tsx
 │   │   └── api/
 │   │       ├── auth/         # NextAuth route
-│   │       └── [[...path]]/  # Single catch-all mounting core's API
+│   │       └── [[...path]]/  # Catch-all for CMS API
 │   ├── lib/
-│   │   ├── data-source.ts    # TypeORM DataSource init
-│   │   ├── auth-helpers.ts   # Wire core auth to NextResponse
-│   │   └── cms.ts            # CmsApp init with plugins
-│   ├── middleware.ts          # Wire core middleware to Next.js
-│   └── ...                   # Your custom pages, components, etc.
+│   │   ├── data-source.ts
+│   │   ├── auth-helpers.ts
+│   │   ├── cms.ts
+│   │   ├── theme-registry.ts
+│   │   └── seed.ts
+│   ├── themes/               # Optional: default theme from init
+│   ├── migrations/
+│   ├── middleware.ts
+│   └── ...                   # Your pages, components, etc.
 ```
 
 ## Getting Started
@@ -40,28 +49,14 @@ npx create-next-app@latest my-website --typescript --tailwind --app --src-dir
 cd my-website
 ```
 
-### 2. Install core
-
-Link the local package (or install from npm once published):
+### 2. Install the package
 
 ```bash
-# In your website's package.json, add:
-#   "@infuro/cms-core": "file:../core"
-npm install
+npm install @infuro/cms-core typeorm reflect-metadata bcryptjs next-auth next-themes sonner
+npm install -D @types/node
 ```
 
-Required peer dependencies (should already be in a Next.js app):
-
-```
-next >= 14, react >= 18, react-dom >= 18, next-auth ^4.24
-```
-
-Additional dependencies you'll need:
-
-```bash
-npm install typeorm reflect-metadata bcryptjs next-auth next-themes sonner
-npm install -D @types/node typescript
-```
+Peer dependencies (Next.js app usually has these): `next` ≥14, `react` ≥18, `react-dom` ≥18, `next-auth` ^4.24. For local development, use `"@infuro/cms-core": "file:../core"` in package.json and run `npm install`.
 
 ### 3. Configure `next.config.js`
 
@@ -306,8 +301,22 @@ export async function POST(req: Request) {
 
 Create `src/app/admin/layout.tsx`:
 
-```ts
-export { default } from '@infuro/cms-core/admin';
+```tsx
+'use client';
+import '@infuro/cms-core/admin.css';
+import AdminLayout from '@infuro/cms-core/admin';
+
+export default function AdminLayoutWrapper({ children }: { children: React.ReactNode }) {
+  return (
+    <AdminLayout
+      customNavItems={[]}
+      customNavSections={[]}
+      customCrudConfigs={{}}
+    >
+      {children}
+    </AdminLayout>
+  );
+}
 ```
 
 Create `src/app/admin/[[...slug]]/page.tsx`:
@@ -321,20 +330,20 @@ export default async function AdminPage({ params }: { params: Promise<{ slug?: s
 }
 ```
 
-That's it — the admin panel at `/admin` is fully rendered by core (layout, sidebar, header, pages). Core injects its own CSS theme variables via `<style>` tag, so no additional CSS setup is needed for the admin panel.
+The admin at `/admin` is rendered by the package (layout, sidebar, header, built-in pages). Pass `customNavSections` and `customCrudConfigs` to add your own sidebar links and CRUD list pages (see [Adding custom pages and admin nav](#adding-custom-pages-and-admin-nav)).
 
 ### 10. Configure Tailwind
 
-Core's admin components use Tailwind classes. Your `tailwind.config.js` must scan core's source so those classes aren't purged in production:
+Core's admin components use Tailwind classes. Include the package in `content` so those classes aren't purged:
 
 ```js
-module.exports = {
-  content: [
-    "./src/**/*.{js,ts,jsx,tsx,mdx}",
-    "../core/src/**/*.{js,ts,jsx,tsx}",   // include core
-  ],
-  // ... rest of your config
-};
+content: [
+  "./src/**/*.{js,ts,jsx,tsx,mdx}",
+  // When using from npm:
+  "./node_modules/@infuro/cms-core/dist/**/*.{js,cjs}",
+  // When using file:../core (local):
+  // "../core/src/**/*.{js,ts,jsx,tsx}",
+],
 ```
 
 You also need the shadcn/ui color mappings in `theme.extend.colors` — see the [Tailwind Config](#tailwind-config) section below.
@@ -348,7 +357,19 @@ import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
 import { createCmsMiddleware } from '@infuro/cms-core/auth';
 
-const cmsMiddleware = createCmsMiddleware();
+const cmsMiddleware = createCmsMiddleware({
+  // Optional: allow unauthenticated access to specific API paths/methods (e.g. public form submit)
+  publicApiMethods: {
+    '/api/contacts': ['POST'],
+    '/api/form-submissions': ['POST'],
+    '/api/blogs': ['GET'],
+    '/api/forms': ['GET'],
+    '/api/auth': ['GET', 'POST'],
+    '/api/users/forgot-password': ['POST'],
+    '/api/users/set-password': ['POST'],
+    '/api/users/invite': ['POST'],
+  },
+});
 
 export function middleware(request: NextRequest) {
   const result = cmsMiddleware({
@@ -408,6 +429,16 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+## Adding custom pages and admin nav
+
+**Custom sidebar links:** Pass `customNavItems` or `customNavSections` to `AdminLayout` in your `src/app/admin/layout.tsx`. Each item has `href`, `label`, and optional `icon`. Use `href` like `/admin/locations` so the link opens under the admin.
+
+**Custom CRUD (list + optional add/edit):** Define a `CustomCrudConfig` (title, apiEndpoint, columns, addEditPageUrl, optional filters) and pass it as `customCrudConfigs={{ myResource: config }}` to `AdminLayout`. You must have a corresponding API (e.g. under your catch-all or a custom route) and entity. The first path segment (e.g. `locations`) is the key; add a nav item with `href: '/admin/locations'`.
+
+**Custom full pages:** For a page that isn’t a CRUD list, add a Next.js route under admin, e.g. `src/app/admin/reports/page.tsx`, and render your component there. The admin layout wraps all `/admin/*` routes, so your page appears inside the same shell. Add a link in `customNavItems` or `customNavSections` with `href: '/admin/reports'`.
+
+Types are exported from `@infuro/cms-core/admin`: `CustomNavItem`, `CustomNavSection`, `CustomCrudConfig`, `CustomCrudColumn`, etc.
+
 ## Database Setup
 
 ### First-time setup (quick)
@@ -586,13 +617,13 @@ createCmsMiddleware({
 
 ## Tailwind Config
 
-Core's admin panel and UI components use shadcn/ui which requires CSS variable-based color mappings. Your `tailwind.config.js` needs these in `theme.extend.colors`:
+The admin panel and UI components use shadcn/ui and require CSS variable-based color mappings. Your `tailwind.config.js` needs these in `theme.extend.colors`:
 
 ```js
 module.exports = {
   content: [
     "./src/**/*.{js,ts,jsx,tsx,mdx}",
-    "../core/src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@infuro/cms-core/dist/**/*.{js,cjs}",
   ],
   darkMode: "class",
   theme: {
@@ -632,7 +663,7 @@ module.exports = {
 };
 ```
 
-The CSS variables themselves are injected by core's AdminLayout at runtime. Your website's own CSS can also define them in `:root` if your public pages use shadcn/ui components.
+The CSS variables are injected by the admin layout at runtime. Your website's own CSS can also define them in `:root` if your public pages use shadcn/ui components.
 
 ## Environment Variables