@infuro/cms-core 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,31 @@
 # @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.
+
+## Overview
+
+**What you need to set up a new site:**
+
+- Next.js 14+ app with TypeScript and Tailwind
+- PostgreSQL and env vars: `DATABASE_URL`, `NEXTAUTH_SECRET`, `NEXTAUTH_URL`
+- A few files in your app: **data-source** (TypeORM), **auth-helpers**, **cms** (plugins), **API catch-all route**, **NextAuth route**, **admin layout + catch-all page**, **middleware**, **providers** (Session + Theme + Toaster)
+- Tailwind config that includes the package in `content` and extends theme (shadcn-style colors)
+- Optional: custom admin nav, custom CRUD configs, custom admin pages, plugins
+
+**Install from npm:**
+
+```bash
+npm install @infuro/cms-core typeorm reflect-metadata bcryptjs next-auth next-themes sonner
+npm install -D @types/node
+```
+
+For local development with the core package in a sibling folder:
+
+```json
+"@infuro/cms-core": "file:../core"
+```
+
+Then follow the setup steps below.
 
 ## Architecture
 
@@ -42,26 +67,12 @@ cd my-website
 
 ### 2. Install core
 
-Link the local package (or install from npm once published):
-
 ```bash
-# In your website's package.json, add:
-#   "@infuro/cms-core": "file:../core"
-npm install
-```
-
-Required peer dependencies (should already be in a Next.js app):
-
-```
-next >= 14, react >= 18, react-dom >= 18, next-auth ^4.24
+npm install @infuro/cms-core typeorm reflect-metadata bcryptjs next-auth next-themes sonner
+npm install -D @types/node
 ```
 
-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 +317,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 +346,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 core (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 +373,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 +445,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)