Remove a feature you don't use

Examples used to test this page: the blog and the admin MCP server, each removed from a fresh copy of the template by following the steps below literally, until verify was green. Billing was left switched off rather than removed; its section says why.

Check the first section before you delete anything: a feature that stays off without its env vars may be all you need, and switching it off leaves nothing to resolve when you merge upstream.

Switched off until you configure it

Two features have no off switch:

• The backend's email queue. SMTP_FROM is required at boot. Without SMTP_HOST the backend logs a warning and sends to localhost:1025, so every queued email fails and is retried until it runs out of attempts.
• The admin MCP server. It has no key of its own: an agent connects only after an admin signs in and allows it, so with no admins nobody can connect, but the routes, the OAuth endpoints, the consent page and the backoffice screen are still there. To have no MCP server, remove it as below.

The blog has no switch either: with no posts, /blog and its links stay.

Teams and workspaces are not a feature to remove. Every user has a personal workspace, items belong to a workspace, and account deletion, the item cap and the frontend's item pages all read it. A product with no teams can leave the shared-workspace UI unused: nobody gets a second workspace or an invite unless they create one. The email queue it sends invites through is the one above, and the invite link is built from FRONTEND_URL.

Before you remove anything

Three rules hold for every section below.

• Never edit or delete a migration that has run. Knex records every file it ran, and a missing one stops every later npm run migrate with The migration directory is corrupt, the following files are missing (Updating from upstream). The feature's tables go with a new migration that drops them; see Drop the tables.

• Delete the tests with the code. A spec of a deleted file fails to compile, and the guard specs (route-auth.spec.ts, deletion-policy.integration.spec.ts) fail on entries for what is gone.

• Regenerate the contract and types after the backend change, from backend/:

  npx ts-node -r tsconfig-paths/register scripts/dump-openapi.ts
  cp openapi.runtime.json ../openapi.json
  cp openapi.internal.runtime.json ../openapi.internal.json
  cd ../frontend && npm run generate-types
  

  The frontend then fails npx tsc --noEmit wherever it still uses a removed route or type, which is a good list of what is left to delete.

Run npm run format in each half you changed, then ./verify.sh.

Drop the tables

1. Add a migration named with the next number on disk (look in backend/migrations/), for example backend/migrations/019_drop_blog_posts.ts:

   import { Knex } from 'knex';
   
   /**
    * Drops the blog's table, with its posts. Dropping it also drops its
    * indexes and its foreign key to `users`.
    *
    * `down` cannot bring the posts back, so it refuses rather than recreate an
    * empty table: restore a backup taken before this ran instead.
    */
   export async function up(knex: Knex): Promise<void> {
     await knex.schema.dropTableIfExists('blog_posts');
   }
   
   export async function down(): Promise<void> {
     throw new Error('019_drop_blog_posts cannot be undone: restore a backup');
   }
   

   Back up production before you deploy it. The rows are gone once it runs.

2. Remove the table's entry from DELETION_POLICY in backend/src/users/deletion-policy.ts. deletion-policy.integration.spec.ts compares the entries with the migrated database, so it fails until the entry is gone.

What this means for upstream merges. Upstream keeps its migrations, so 001_initial.ts still creates the table and yours drops it; that merges without a conflict. Three things need you:

• An upstream migration that later changes a table you dropped fails on your database, and in verify, which migrates a fresh one. Leave the file in place and make its up return early when the table is gone, with if (!(await knex.schema.hasTable('blog_posts'))) return;. Do not delete it: once a deploy has recorded it, its absence is the corrupt-directory error.
• An upstream change to a file you deleted arrives as a deleted by us conflict. git rm the file again, and read the change in case it touched a file you kept as well.
• Upstream edits to the POLICY or DELETION_POLICY entries you removed conflict with your removal. Keep your side.

Remove the blog

The blog is the public /blog pages, the backoffice blog screens, the blog backend module, the blog tools on the admin MCP server and the blog_posts table. If you are removing the admin MCP server as well, do that first and skip the mcp-admin steps here.

Backend

1. Delete backend/src/blog/ (the module, both controllers, the service, the schemas and its four specs), backend/src/common/reading-time.ts and its spec, and backend/src/mcp-admin/mcp-admin-blog.tools.ts and its spec.
2. backend/src/app.module.ts: remove the BlogModule import and its entry in imports.
3. The admin MCP server's blog tools.
   • mcp-admin/mcp-admin.module.ts: remove BlogModule from the imports.
   • mcp-admin/mcp-admin-tools.service.ts: remove the BlogService and registerBlogTools imports, the blogService constructor parameter, the registerBlogTools(...) call and "blog authoring, " from ADMIN_SERVER_DESCRIPTION.
   • mcp-admin/mcp-admin-tools.service.spec.ts: one {} as never fewer in buildService, the three admin_*_blog_post entries in writes, and updates from the import, which nothing else uses (lint fails: 'updates' is defined but never used).
   • mcp-admin/mcp-admin.service.ts: the BLOG: line in SERVER_INSTRUCTIONS and "blog deletes are permanent" in its last paragraph.
4. backend/src/common/route-auth.spec.ts: remove the BlogController and AdminBlogController entries from POLICY. Left in, "states a policy for every registered controller, and only those" fails and names them. In route-auth.http.spec.ts, remove ['GET', '/admin/blog/posts'] from ADMIN_ROUTES and ['GET', '/blog/posts'] from PUBLIC_ROUTES.
5. backend/src/common/body-parsers.ts: remove the blogWriteJson parser and the comment above it. It raises the body limit to 640kb for the two blog write routes; nothing else needs it.
6. backend/src/db/types.ts: remove BlogPostRow.
7. backend/src/scripts/seed.ts: remove the calculateReadingTime import, slugify, the "Blog Posts" section (postsData and buildBlogPosts), the "Seeding blog posts" block in seed() and the Blog Posts: summary line.
8. The table: drop blog_posts. The comment in the "keeps the row" test of users.service.integration.spec.ts names blog_posts.published_by; drop that clause.
9. Regenerate openapi.json and the frontend types.

Frontend

10. Delete app/blog/, app/backoffice/blog/, lib/blog.ts, lib/blog.test.ts, lib/markdown.ts and lib/markdown.test.ts. Only blog posts were markdown, so uninstall what rendered it, or knip fails on Unused dependencies:

    npm uninstall marked isomorphic-dompurify
    

11. Links and types. In lib/site.ts, remove the /blog entry from links. In lib/api.ts, remove the BlogPost and AdminBlogPost types.

12. app/sitemap.ts lists the posts. With none left it is just the home page:

    import { MetadataRoute } from 'next';
    import { site } from '@/lib/site';
    
    export default function sitemap(): MetadataRoute.Sitemap {
      return [
        {
          url: site.url,
          lastModified: new Date(),
          changeFrequency: 'daily',
          priority: 1,
        },
      ];
    }
    

13. app/llms.txt/route.ts: remove the Blog line, so the list ends - Home${pricingLine}.

14. proxy.ts: remove BLOG_SLUG_PATTERN, blogPostExists and the blogSlugMatch check in proxy(), and change the header comment from four jobs to three (the admin gate, the 404 for dormant /pricing, the CSP nonce). In proxy.test.ts, remove describe('/blog/<slug>').

15. The backoffice. In app/backoffice/Shell.tsx, remove the Blog entry from NAV. In app/backoffice/page.tsx, remove the posts fetch from Promise.all (and AdminBlogPost from the import, and '/admin/blog/posts' from the path type of recent), the "New post" button, the "Blog posts" KPI cell and the "Latest posts" RailList.

16. The messages. In messages/en.json (and any translation), delete Blog, Backoffice.blog and Backoffice.postForm, plus Nav.blog, Backoffice.nav.blog, Backoffice.nav.newPost, Backoffice.nav.editPost, and Backoffice.overview.posts, latestPosts, postsFailed, noPosts and publishedOn. Nothing fails if one stays; it is dead text a translator would still be asked for.

17. What knip then finds unused.

    • Textarea and Checkbox in components/ui/Input.tsx and FormActions in components/ui/FormSection.tsx: the post form was their only user. They are building blocks you will likely want for your own forms, so keep them by tagging each with @public in its doc comment, which knip skips:

      /** @public */
      export function Textarea({ className, ...props }: ComponentProps<'textarea'>) {
      

      Or delete them and their names in frontend/CLAUDE.md "Layout".

18. Comments that name the blog. app/layout.tsx says the data cache is what lib/blog.ts relies on; make that lib/billing.ts, which still does. The top of app/styles/_prose.scss says blog bodies and lib/markdown.ts; it styles the legal pages now. In next.config.ts, the images.unsplash.com entry in remotePatterns was only for the sample posts; remove it (an empty remotePatterns: [] is fine), and https://images.unsplash.com from img-src in the CSP in proxy.ts. In package.json, //engines gives isomorphic-dompurify as a reason for the Node 24 floor; drop it from that sentence, leaving jsdom. Four comments still name the blog in passing: app/backoffice/users/actions.ts ("the blog list's publish toggle"), app/styles/_type.scss ("Blog, Sign in, 404"), lib/billing.test.ts ("Same contract as lib/blog.ts") and lib/fetch-timeout.test.ts ("the blog and billing reads"); reword them. In lib/fetch-timeout.test.ts, the /blog/posts URLs are only strings for a mocked fetch and can stay.

19. CI. The "No EACCES under real traffic" step in .github/workflows/ci.yml curls http://localhost:3000/blog, which is now a 404 and fails the step. Curl http://localhost:3000/ instead, and say "the landing page" for "a cached fetch on the blog" in the comment above it: the landing page reads billing status through the same data cache.

Docs that describe the blog

git grep -il blog -- docs README.md backend/CLAUDE.md frontend/CLAUDE.md lists them. Rewrite the ones that describe the blog as a feature, and the examples that point at deleted code.

Remove the admin MCP server

The server is backend/src/mcp-admin/ on top of backend/src/mcp-shared/, which holds the stateless transport, the rate limiter and the OAuth 2.1 pieces (discovery, Dynamic Client Registration, PKCE, the approve endpoint and the signed tokens). The admin server is their only user, so both go. If you plan a server of your own, keep mcp-shared/ instead; knip then reports its files as unused until your server imports them. The frontend consent page, the backoffice "MCP connections" screen and the mcp_admin_oauth_grants and mcp_admin_oauth_clients tables go with it.

Backend

1. Delete backend/src/mcp-admin/, backend/src/mcp-shared/ and backend/src/common/escape-html.ts, which only the OAuth error page used (knip: Unused files). Then:

   npm uninstall @modelcontextprotocol/sdk
   

2. backend/src/app.module.ts: remove the McpAdminModule import and its entry.

3. backend/src/common/route-auth.spec.ts: remove five POLICY entries: McpAdminGrantsController and the four the OAuth factory built, McpAdminServiceDiscoveryController, McpAdminServiceOAuthController, McpAdminServiceConsentController and McpAdminServiceTransportController, with the comment above them. In route-auth.http.spec.ts, remove the two /admin/mcp/grants paths from ADMIN_ROUTES, /admin/mcp/oauth/approve from SESSION_ROUTES, and the "refuses MCP consent to a signed-in non-admin" test.

4. backend/src/common/validate-secrets.ts: drop "and keys the admin MCP server's OAuth tokens" from the comment above REQUIRED_SECRETS.

5. backend/src/common/client-ip.spec.ts: delete the describe('a rate-limited route behind clientIpMiddleware') block and the four imports only it used (Server, AddressInfo, registerRateLimited, resetRateLimits). It tested the header through the MCP rate limiter; the middleware's own tests above it stay.

6. backend/src/common/body-parsers.ts: remove the express.urlencoded parser and its comment; only the OAuth /token form posted urlencoded bodies. Drop "on the MCP endpoint" from the JSON parser's comment, and in src/main.ts make the comment above NestFactory.create say it installs the raw parser the Stripe webhook needs.

7. backend/src/db/types.ts: remove McpAdminOAuthGrantRow and McpAdminOAuthClientRow. In backend/src/common/frontend-url.ts, drop "and the admin MCP consent page" from the comment.

8. Leave MCP_ADMIN_USER_ID in backend/src/users/users.service.ts. Migration 003 seeded that system user and the row stays in your database; auth-adapter.service.ts uses the id to keep anyone from signing in as it. Reword its comment to "A system user seeded by migration 003", since no tools write as it any more.

9. Stale specs. If you kept the blog, delete "keeps the 32kb cap on the admin MCP endpoint" in src/blog/blog-body-limit.http.spec.ts.

10. The tables: drop mcp_admin_oauth_clients and mcp_admin_oauth_grants, in a migration with the next number on disk. Take both out of DELETION_POLICY in backend/src/users/deletion-policy.ts.

11. Env vars. BACKEND_URL was read only by the MCP OAuth discovery documents, and ADMIN_MCP_OAUTH_REDIRECT_ORIGINS and MCP_RATE_LIMIT_PER_MIN only by the server. Remove:

    • backend/.env.example: the BACKEND_URL block, the commented ADMIN_MCP_OAUTH_REDIRECT_ORIGINS with its comment, the sentence on MCP tokens under INTERNAL_API_TOKEN, and the MCP_RATE_LIMIT_PER_MIN block.
    • deploy/.env.prod.example: the admin MCP lines under INTERNAL_API_TOKEN, the commented ADMIN_MCP_OAUTH_REDIRECT_ORIGINS, and # MCP_RATE_LIMIT_PER_MIN=1200.
    • deploy/docker-compose.prod.yml: BACKEND_URL, MCP_RATE_LIMIT_PER_MIN and ADMIN_MCP_OAUTH_REDIRECT_ORIGINS under backend.
    • deploy/Caddyfile: the header comment's reasons for the api subdomain name /admin/mcp/oauth, the discovery documents and BACKEND_URL; /openapi.json and the API paths are reason enough.
    • Your own backend/.env and the deployed environment.

12. Regenerate openapi.json and the frontend types.

Frontend

13. Delete app/mcp/ and app/backoffice/connections/, remove the connections entry from NAV in app/backoffice/Shell.tsx, and the McpAuthorize and Backoffice.connections messages from messages/en.json.
14. app/llms.txt/route.ts: remove the "For agents operating this app" section.
15. frontend/.env.example: the NEXT_PUBLIC_API_URL comment gives "the MCP install command" as its example; the API link in /llms.txt is one that still exists.

Docs that describe the server

Delete docs/Admin MCP Server.md, the "MCP servers" section of backend/CLAUDE.md, and the "Add an MCP tool" row in AGENTS.md. Then git grep -il mcp -- docs README.md AGENTS.md backend/CLAUDE.md .claude lists the rest.

Remove workspace API keys

The keys are backend/src/api-keys/, the api_keys table and the API keys section of Settings. SessionGuard's refusal of key-shaped tokens (src/auth/api-key-shape.ts) is harmless without them and can stay.

Backend

1. Delete backend/src/api-keys/, and remove ApiKeysModule from app.module.ts.
2. Items go back to sessions. In items.controller.ts, replace @UseGuards(WorkspaceMemberOrApiKeyGuard) with @UseGuards(SessionGuard, WorkspaceMemberGuard) and drop viaApiKey: m.viaApiKey === true; in items.module.ts, import AuthModule in place of ApiKeysModule; in items.controller.spec.ts, override SessionGuard and WorkspaceMemberGuard. viaApiKey can go from CreateItemArgs, WorkspaceMembership and lockWorkspaceRole, with the false every other caller passes.
3. backend/src/common/route-auth.spec.ts: remove the ApiKeysController entry, MEMBER_OR_API_KEY and the test that checks it, and make ItemsController classGuards: MEMBER.
4. backend/src/db/types.ts: remove ApiKeyRow and ApiKeyWithCreatorRow.
5. The table: drop api_keys in a migration with the next number on disk.
6. Regenerate openapi.json and the frontend types.

Frontend

7. Delete app/settings/ApiKeys.tsx and CreateApiKeyForm.tsx, remove getApiKeys and the <ApiKeys> section from app/settings/page.tsx, the two key actions from workspace-actions.ts, and the ApiKey type and .keyReveal style.

Docs that describe the keys

The "API keys" section and the two roles rows in docs/Teams and Workspaces.md, the api-keys rows in docs/Architecture/4 REST Surface.md, and the API keys row in AGENTS.md. git grep -il "api key" -- docs AGENTS.md backend/CLAUDE.md .claude lists the rest.

Billing: leave it switched off

Billing is not removable in a few steps. It is wired into three features you keep:

• The free-plan cap. ItemsService.create reads the workspace owner's getEntitlement and caps an owner without paidAccess at 100 items across their workspaces. With billing off, that is every owner.
• Account deletion. The deletion worker's second half is deleteCustomerData, which deletes the Stripe customer when billing is on, and deletion-policy.ts has an entry for each of the five billing_* tables.
• Housekeeping. session-cleanup.worker.ts sweeps billing_webhook_events and billing_payment_hook_claims.
• One-time purchases. src/purchases/ is bound to billing as its payment hook in app.module.ts, and getEntitlement asks it for lifetime grants.

To leave it off, unset every STRIPE_* variable and do nothing else; the first section lists what then stays hidden. If the item cap is the only part that bothers you, lift it in ItemsService.create, which is one if.

Removing it fully touches the item cap, account deletion, both workers, the guard specs, five tables plus purchase_grants, the purchases module, and most of frontend/app/; it was not run end to end for this page. Keep FRONTEND_URL if you do: workspace invite links, Stripe return URLs and the admin MCP consent page are built from it.

What the test run found

• Blog, following its section on a fresh copy: the first verify failed at backend lint on the updates import in mcp-admin-tools.service.spec.ts, now a step above. Frontend knip reported Textarea, Checkbox and FormActions. With the original package.json put back, it also reports marked and isomorphic-dompurify under Unused dependencies. With every step done, verify: all green (integration specs ran).
• Admin MCP server: backend knip reported src/common/escape-html.ts once mcp-shared/ was gone, and @modelcontextprotocol/sdk under Unused dependencies until it was uninstalled. With both done, verify: all green (integration specs ran) on the first full run.
• Billing was not removed. The template's own verify runs with every STRIPE_* unset, which is the switched-off state, and is green.
• The early return for an upstream migration that alters a dropped table was not exercised: no such upstream migration exists yet.

Related

• Updating from upstream - merging after a removal
• What Ghost Deletion Erases - the deletion policy
• Testing - the guard specs a removal trips
• What refuses boot