Set up your blog, your way.

MANUAL SETUP

Set it up yourself

1. STEP 01

   Read the license and retain the footer credit

   • Read https://nextjsblog.com/terms and preserve the supplied LICENSE and copyright notices.
   • Personal and commercial publication use requires a visible, direct Powered by nextjsblog.com link to https://nextjsblog.com in the footer of every public blog page: landing, article, pagination, category, tag and author pages.
   • Retain ProductCredit in the shared blog footer, or add it to the host blog layout when reusing its shell.
   • Keep the credit readable on mobile and desktop, keyboard accessible and present without JavaScript; do not hide it or route it through a redirect.
   • Link qualifiers such as rel="nofollow" are the site owner's choice.
   • Preserve the host's own identity and canonicals.
   • Resale, white-labeling, and offering the software or derivatives as a commercial product or service are prohibited even with attribution; building or hosting a client's own blog as a service is allowed.
   • Third-party materials retain their own licenses.

2. STEP 02

   Inspect your existing website

   • Work in the existing checkout.
   • Read repository instructions and Git status, then identify the target app workspace, router, Node/Next/React versions, packageManager field, lockfile and CI commands.
   • Preserve its project name, branding, canonical domain and deployment.
   • Install only missing compatible dependencies with its current npm, pnpm, Yarn or Bun workflow.
   • Resolve conflicting lockfiles from workspace/CI evidence; ask if ambiguous.
   • Do not clone the starter over the app, replace package.json, switch package managers or upgrade the framework automatically.
   • This is currently a source integration; no installable npm package is released.
   bash

   git status --short
   node --version
   node -p "require('./package.json').packageManager || 'Check lockfiles and CI'"

3. STEP 03

   Map routes and existing features

   • Create a route map before copying files: /blog, /dashboard, /api, login, RSS, sitemap, robots, search and social images.
   • Include src/app, route groups, dynamic/catch-all routes, Pages Router, redirects, rewrites, middleware/proxy, basePath and locales.
   • Reuse the site's shell, global CSS, metadata, auth and analytics.
   • Merge sitemap/feed entries without replacing other site URLs.
   • If a route is occupied, ask whether to reuse it or choose another mount; update all links, handlers, metadata, feeds and redirects together.
   • The starter has hardcoded routes; a custom mount requires code changes, not just publishing.json.
   • Pages Router, non-Next apps or incompatible versions require an agreed adaptation plan before installation.

4. STEP 04

   Protect existing content and login

   • Inspect app/blog and any publishing.json before writing.
   • The folder is relative to the selected app root, not the monorepo root; object storage uses it as a bucket prefix.
   • Check Markdown/MDX formats, authors, assets, duplicate slugs and existing CMS ownership.
   • Keep original content, URLs and frontmatter; propose an explicit migration with backups and redirects when formats differ.
   • Never add demo posts or replace existing settings.
   • Reuse a compatible completed installation on retries; incompatible configuration needs a migration decision.
   • Preserve the website's authentication even in Local mode.
   • For login-based setup, inspect existing sessions and /login first; reuse compatible Supabase Auth or agree on an isolated blog login.
   • Never replace another auth system or treat every logged-in site user as a blog editor.

5. STEP 05

   Mount the blog at /blog

   • Check /blog against existing static, dynamic and catch-all routes before edits.
   • Use the site's actual canonical domain; www.xyzdomain.com is only a UI placeholder.
   • The starter defaults to /blog.
   • A custom route is an integration request: update route files, links, API callers, canonical metadata, feeds, sitemap and redirects together and verify them.
   • Downloading this configuration does not relocate routes automatically.

6. STEP 06

   Keep existing content untouched

   • Keep the existing CMS, posts, assets and routes unchanged.
   • Add the new blog alongside them in an unused folder and route.
   • If the selected folder or route already contains content, ask for an alternate or an explicit merge decision; do not import, overwrite, delete or disconnect existing content.
   • The user will port old data themselves; provide a field mapping for later use without migrating anything now.

7. STEP 07

   Prepare app/blog

   • Create app/blog/posts and app/blog/settings.json inside the app repository.
   • Follow the selected existing-content policy first.
   • Copy only content approved for migration without overwriting originals; for a separate or fresh blog, create empty posts and minimal settings.
   • Never copy demo posts into an existing website.
   • Retain image URLs under public/blog.
   • In app/ or src/app/, store data only in posts/*.md and settings.json; leave page.tsx, layouts, route handlers and other source files intact.
   • Reject traversal and symlinks.
   • No provider account or database is required for local writing.
   bash

   # After confirming this folder is safe to use
   mkdir -p -- 'app/blog/posts'

8. STEP 08

   Apply your configuration

   • Merge the validated publishing.json into the selected app root only after resolving existing configuration and content conflicts.
   • Preserve the site's identity and canonical URL; derive blog metadata from them.
   • Wire readers, writers, settings and content audit to the same content root, include it in build tracing, and restart using the app's existing development command.
   • This configuration is required to select a non-default content folder.
   • Create or merge publishing.json in the app root; never overwrite an existing configuration without reviewing its differences.
   json · publishing.json

   {
     "schemaVersion": 2,
     "installation": "existing",
     "projectName": null,
     "mode": "local",
     "destination": "github",
     "contentPath": "app/blog",
     "blogRoute": "/blog",
     "existingContent": "keep",
     "loginRoute": null,
     "authentication": "none",
     "oauth": false,
     "assets": "repository",
     "database": "none",
     "hosting": "existing",
     "projectScope": "single-project"
   }

9. STEP 09

   Write and preview

   • Open the resolved Studio editor route locally (the starter uses /dashboard/editor), save a post and verify it appears in app/blog/posts.
   • Verify settings persist to app/blog/settings.json.
   • Draft and future-dated posts must stay out of public outputs.
   • Public Git history and public/ assets are not made private by this filter.

10. STEP 10

    Validate your installation

    • Run the checks, inspect your diff, and verify a local save/read plus public draft exclusion.
    • Review and commit content explicitly; local saving does not publish it.
    • Run the existing workspace's actual scripts with its detected package manager, recording the baseline separately.
    • Add focused integration checks where missing; do not assume starter script names exist.
    • Verify existing home/product pages, original auth, APIs and SEO outputs still work, plus the resolved blog/Studio routes.
    • Do not deploy when integration checks fail.
    bash

    git diff --check
    git diff --stat

11. STEP 11

    Keep your current deployment

    • Detected/selected hosting: existing.
    • Preserve the domain, hosting account, workspace build settings and CI/deploy workflow.
    • Check whether the existing target supports the integrated Next.js server features; static export, edge-only runtimes and read-only filesystems may need adaptation.
    • Publish committed content through the current build and keep hosted Studio read-only.
    • Request a decision if incompatible; do not switch providers or create a new hosting project automatically.
    • Deploy only within the user's authorization and verify existing pages alongside the blog.