next-blogpanel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blogforge-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# Next BlogPanel
+
+A drop-in blog engine for Next.js — admin panel, block editor, SEO, and media, all backed by your own MongoDB.
+
+`next-blogpanel` scaffolds a working blog into an existing Next.js App Router project: public pages, an admin CMS, and API routes. You own the database, the files, and the URLs. There is no hosted service and no third-party account to create.
+
+## Features
+
+- **Block editor** — TipTap with slash commands, image upload, Shiki code blocks, callouts, FAQ blocks, tables, task lists
+- **Admin panel** — dashboard, post list, block editor, media library, category manager, settings, scoped API tokens
+- **SEO** — meta tags, Open Graph, Twitter Cards, JSON-LD (`BlogPosting`, `BreadcrumbList`, `FAQPage`), sitemap, RSS, and a 17-check SEO scorer
+- **Images stored in your MongoDB by default; Cloudflare R2 optional; anything else pluggable** — GridFS needs no setup at all, R2 takes over when you supply its five environment variables, and `StorageProvider` is public API for the rest
+- **MongoDB backend** — CRUD, slug generation, revision history, full-text search
+- **Components** — two page-level components with slot injection, plus eleven atomic ones for building your own layout
+- **Theming** — colours, fonts, radii and shadows are `--nbp-*` CSS variables, dark mode included
+- **CLI** — `init`, `migrate`, `seed`, `health`
+
+## Prerequisites
+
+- Node.js 18+
+- Next.js 14+ using the App Router
+- MongoDB — Atlas free tier is enough, and it stores your images too
+
+No object storage account is required.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pnpm add next-blogpanel     # or: npm install next-blogpanel
+```
+
+### 2. Scaffold
+
+```bash
+npx next-blogpanel init
+```
+
+Into your existing `app/` (or `src/app/`) directory this writes:
+
+- `app/blog/` — layout, list page, `[slug]` post page, `category/[slug]` page
+- `app/admin/blog/` — layout, dashboard, posts, new, `[id]/edit`, media, categories, settings
+- `app/api/blog/` — posts, media, `media/file/[...key]`, categories, settings, tokens, `sitemap.xml`, `rss.xml`
+- `app/next-blogpanel.setup.ts` — hands your config file to the server at runtime; every scaffolded file imports it
+
+…and at the project root, `next-blogpanel.config.ts` and `.env.local.example`. The API routes and admin pages are one-line re-exports; the blog pages are real source built from the atomic components, so they are the ones to edit when you want a different layout. Files that already exist are skipped, never overwritten.
+
+### 3. Configure the environment
+
+```bash
+cp .env.local.example .env.local
+```
+
+```env
+BLOGPANEL_MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/mydb
+BLOGPANEL_API_KEY=a-secure-key-of-at-least-32-characters
+```
+
+Those two are the only variables you need. Generate the key with `openssl rand -hex 32`.
+
+> The generated `.env.local.example` also contains five `BLOGPANEL_R2_*` placeholder lines. **Delete or comment them out unless you have a real Cloudflare R2 bucket.** All five being set — even to placeholder text — is what switches image storage from MongoDB to R2, and uploads will then fail against credentials that do not exist. See [docs/storage.md](docs/storage.md).
+
+Other optional variables: `BLOGPANEL_MONGODB_DB` (overrides the database named in the URI), `BLOGPANEL_SITE_URL` and `BLOGPANEL_SITE_NAME` (used in meta tags, sitemap and RSS; default to `""` and `"Blog"`), and `BLOGPANEL_STORAGE`.
+
+`BLOGPANEL_SITE_URL` is optional to start but required before you deploy. Images stored in GridFS get root-relative URLs, and `og:image`, `twitter:image`, JSON-LD `image` and RSS `<enclosure>` all have to be absolute — so without it those four are omitted (with a warning) rather than emitted as URLs no crawler can resolve.
+
+### 4. Create the indexes
+
+```bash
+npx next-blogpanel migrate
+```
+
+Creates the MongoDB indexes. If it finds media documents from a pre-1.0 install it upgrades their schema at the same time. Safe to re-run.
+
+### 5. Run
+
+```bash
+pnpm dev
+```
+
+- Blog — <http://localhost:3000/blog>
+- Admin — <http://localhost:3000/admin/blog>
+
+The admin panel asks for your `BLOGPANEL_API_KEY` on first visit and validates it against the server before letting you in. From there, **New Post** opens the block editor — type `/` for the command menu — and publishing puts the post on the blog immediately. To see the whole thing populated before writing anything, `npx next-blogpanel seed` inserts three categories and an example post.
+
+## Paths
+
+> **Three independent paths, and all three are defaults you own.** Set them at
+> `init` and every scaffolded folder, link, and fetch follows. Nothing in the
+> package hardcodes the word "blog".
+>
+> ```bash
+> npx next-blogpanel init --blog-path /articles --admin-path /admin/articles --api-path /api/articles
+> ```
+
+The three flags default to `/blog`, `/admin/blog` and `/api/blog`. Whatever you pass is written into the scaffolded directory names, into the `basePath`/`adminPath`/`apiPath` props of every generated file, and into `next-blogpanel.config.ts`. `init` refuses paths that resolve to the site root, and refuses any two paths that resolve to the same directory.
+
+Changing the paths later means re-running `init` with the new flags, updating `next-blogpanel.config.ts`, and removing the old folders. `init` warns you when it spots a tree left behind from a previous run.
+
+## Configuration
+
+`next-blogpanel.config.ts` is generated with just the paths and auth strategy. Everything else falls back to a built-in default:
+
+```typescript
+import { defineConfig } from 'next-blogpanel';
+
+export default defineConfig({
+  basePath: '/blog',
+  adminPath: '/admin/blog',
+  apiPath: '/api/blog',
+  postsPerPage: 10,
+  editor: {
+    maxImageSize: 2 * 1024 * 1024,   // stored ceiling — reached by compression
+    maxUploadSize: 10 * 1024 * 1024, // ingest ceiling — enforced by rejection
+    autosaveInterval: 30000,
+  },
+  seo: {
+    titleTemplate: '%s | %siteName%',
+    generateRSS: true,
+    generateSitemap: true,
+    structuredData: true,
+  },
+  features: {
+    search: true,
+    relatedPosts: true,
+    readingProgress: true,
+    tableOfContents: true,
+    shareButtons: true,
+    darkMode: true,
+    scheduling: true,
+    revisionHistory: true,
+    imageOptimization: true,
+  },
+  auth: { strategy: 'api-key' },
+});
+```
+
+The file only takes effect because `app/next-blogpanel.setup.ts` imports it and calls `setConfig()`, and every scaffolded file imports that module in turn. If you hand-write a route handler or server component that calls a `next-blogpanel` API, import the setup module at the top of it too — [docs/configuration.md](docs/configuration.md#getting-the-config-to-the-server) explains why the import has to be repeated rather than done once.
+
+The two image limits are not the same knob and are not interchangeable. `maxUploadSize` (10MB) is the largest file the upload endpoint will accept — anything bigger is rejected with a 413. `maxImageSize` (2MB) is the largest file that will ever be *stored* — anything above it is compressed down, not refused. Full reference: [docs/configuration.md](docs/configuration.md).
+
+## Storage
+
+Uploaded images go into your MongoDB via GridFS by default. That needs no configuration, no extra account, and no extra bill. Budget for it honestly, though: one upload is stored as **up to seven objects** — the WebP original plus five responsive widths and a 200x200 thumbnail — so a photo whose original lands at 200KB occupies roughly 500-800KB in total. On the Atlas free tier that puts 512MB at **several hundred images**, not the couple of thousand the original alone would suggest. Deleting a media item reclaims only the original; the derivatives are not tracked and stay behind. See [docs/storage.md](docs/storage.md).
+
+Add the five `BLOGPANEL_R2_*` variables and Cloudflare R2 takes over automatically. Set `BLOGPANEL_STORAGE` to force a specific backend regardless of what is configured.
+
+Neither one? Implement the exported `StorageProvider` interface, hand the instance to `registerStorageProvider()` in the generated setup module, and set `BLOGPANEL_STORAGE` to its name — Vercel Blob, Supabase Storage, Backblaze B2, ImageKit, UploadThing and plain S3 all fit it. The name is recorded on every media document and read back to route deletes to the right backend; a name that cannot be resolved fails loudly rather than deleting from the wrong one. Worked example in [docs/storage.md](docs/storage.md#custom-storage-providers).
+
+Every upload is re-encoded to WebP and stepped down through quality levels (85 → 75 → 65 → 55) and then width caps (2560 → 1920) until it fits under 2MB. A 5MB photo is stored, just smaller. Only files over the 10MB ingest ceiling are refused outright, along with SVGs over 2MB — sharp cannot meaningfully shrink those. Details, cost comparison and the provider interface: [docs/storage.md](docs/storage.md).
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [docs/configuration.md](docs/configuration.md) | Every config key and environment variable, CLI flags, what `init` scaffolds |
+| [docs/components.md](docs/components.md) | Page-level and atomic components, props, slots, admin components, stylesheets |
+| [docs/api.md](docs/api.md) | REST endpoints, auth, request/response shapes, package exports, slash commands |
+| [docs/theming.md](docs/theming.md) | All CSS variables, colour presets, dark mode |
+| [docs/storage.md](docs/storage.md) | GridFS vs R2, free-tier comparison, the compression ladder, writing a custom `StorageProvider` |
+| [docs/migrating-from-nextblogkit.md](docs/migrating-from-nextblogkit.md) | Upgrading from `nextblogkit` 0.7.x |
+
+## CLI
+
+```bash
+npx next-blogpanel init      # scaffold into your Next.js project
+npx next-blogpanel migrate   # create indexes, upgrade a pre-1.0 media schema
+npx next-blogpanel seed      # insert example categories and a post
+npx next-blogpanel health    # check MongoDB, R2 and environment variables
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | Next.js 14+ (App Router) |
+| Editor | TipTap 2.x |
+| Database | MongoDB (native driver) |
+| Storage | MongoDB GridFS, Cloudflare R2, or any backend you register |
+| Image processing | sharp |
+| Syntax highlighting | Shiki |
+| Validation | Zod |
+| CLI | Commander.js |
+| Build | tsup (ESM + CJS) |
+
+## Developing the package
+
+```bash
+git clone https://github.com/butterblogs/next-blogpanel.git
+cd next-blogpanel
+pnpm install
+pnpm build      # or: pnpm dev, for watch mode
+pnpm test
+```
+
+To try a local build in a real app, `npm pack` here and install the resulting tarball there, then `rm -rf .next` before restarting the dev server.
+
+## License
+
+MIT
+
+---
+
+## Sponsored by ButterBlogs
+
+Next BlogPanel is built and sponsored by [ButterBlogs](https://butterblogs.com), an AI content platform that takes a blog post from research to publication.
+
+The two fit together through the API: draft and optimise in ButterBlogs, then `POST` to your own `/api/blog/posts` endpoint, or paste into the admin editor. ButterBlogs handles content SEO — keyword targeting, EEAT signals, internal linking. Next BlogPanel handles technical SEO — structured data, sitemap, RSS, meta tags — on infrastructure you control.
+
+[Get started with ButterBlogs](https://butterblogs.com)