APOS_MONGODB_URI=mongodb://localhost:27017/my-project
APOS_BASE_URL=http://localhost:3000
NODE_ENV=development
# Optional cluster mode:
# APOS_CLUSTER_PROCESSES=2

4. Add a start script to package.json:

{
  "scripts": {
    "dev": "node app.js",
    "start": "NODE_ENV=production node app.js"
  }
}

5. TypeScript projects: ApostropheCMS is CommonJS. If you need type safety, wrap calls in .js files and import via require. There is no official @types/apostrophe; use JSDoc annotations or a d.ts shim.

6. MongoDB: Start a local instance or point APOS_MONGODB_URI to MongoDB Atlas before running.

Public API

apostrophe(options) — top-level factory

function apostrophe(options: {
  shortName: string;
  modules?: Record<string, object>;
  cluster?: boolean | { processes: number };
  openTelemetryProvider?: object;
  beforeExit?: () => Promise<void>;
}): Promise<AposInstance>;

Called once at startup. Returns the fully initialized Apostrophe instance. shortName is used for cookie names, collection prefixes, and asset namespacing. Pass cluster: true to fork one worker per CPU core; pass cluster: { processes: -1 } to reserve one core for MongoDB on a single-server deployment.

adminBar.add(name, label, permission?, options?) — register an admin bar button

// Accessible via apos.adminBar.add(...)
function add(
  name: string,
  label: string,
  permission?: string | null,
  options?: { after?: string; contextUtility?: boolean }
): void;

Registers a button or menu item in the top admin bar. Called in the init section of any module. permission restricts the button to users holding that permission. Use options.after to position the button relative to another named item.

anyDocType.find(req, criteria, options) — query any document type

// Accessible via apos.anyDocType.find(...)
function find(
  req: AposRequest,
  criteria?: object,
  options?: object
): AposQuery;

Returns a query builder that matches across all document types by removing the implicit type filter (.type(false)). Used when you need to search or relate to any doc regardless of type, such as a universal search feature.

anyPageType.getAutocompleteTitle(doc, query) — format autocomplete labels

function getAutocompleteTitle(
  doc: { title: string; slug: string },
  query: { field: object }
): string;

Returns a display string ("Title (/slug)") for page-type autocomplete fields in relationship schemas. Deprecated in favor of the autocomplete() query builder; shown here for legacy project awareness.

Working examples

Scenario - Minimal Apostrophe application

Initialize a bare-bones Apostrophe site with a custom home page module and the default admin UI.

// app.js
const apostrophe = require('./source/index.js');

apostrophe({
  shortName: 'demo-site',
  modules: {
    'default-page': {
      extend: '@apostrophecms/page-type',
      options: {
        label: 'Default Page'
      }
    },
    '@apostrophecms/page': {
      options: {
        types: [
          { name: 'default-page', label: 'Default Page' }
        ]
      }
    }
  }
});

Scenario - Registering a custom admin bar button

Add a custom button to the admin bar that only appears for users with the admin permission.

// modules/my-tool/index.js
module.exports = {
  init(self) {
    self.apos.adminBar.add(
      'my-tool',
      'My Tool',
      'admin',
      { after: '@apostrophecms/page' }
    );
  }
};

// app.js
const apostrophe = require('./source/index.js');

apostrophe({
  shortName: 'demo-site',
  modules: {
    'my-tool': {}
  }
});

Scenario - Cross-type document query

Fetch all published documents regardless of type from within a custom module method.

// modules/my-search/index.js
module.exports = {
  methods(self) {
    return {
      async searchAll(req, text) {
        const results = await self.apos.anyDocType
          .find(req, {
            $text: { $search: text }
          })
          .project({ title: 1, slug: 1, type: 1 })
          .toArray();
        return results;
      }
    };
  },
  apiRoutes(self) {
    return {
      get: {
        async search(req) {
          const q = req.query.q || '';
          return self.searchAll(req, q);
        }
      }
    };
  }
};

File walkthrough

• index.js - Entry point. Parses CLI args, sets up clustering via Node.js cluster, registers the OpenTelemetry provider, loads all modules through moog-require, and calls apostrophe().
• defaults.js - Baseline options object merged into every Apostrophe instance before user config is applied.
• eslint.config.js - Flat ESLint config for the monorepo; not needed in consumer projects.
• lib/moog.js - The "moog" class/mixin system powering Apostrophe's module inheritance. Modules extend each other through this.
• lib/moog-require.js - Wraps moog to resolve module definitions from the filesystem, npm packages, and project-level overrides.
• lib/glob.js - Sync/async glob wrapper used internally for file discovery.
• lib/opentelemetry.js - Registers a global OpenTelemetry TracerProvider if configured; no-ops otherwise.
• lib/image.js - Image dimension and focal-point utilities.
• lib/locales.js - Locale string normalization helpers.
• lib/safe-json-script.js - Escapes JSON for safe inline <script> emission.
• lib/stream-proxy.js - HTTP stream proxy utility used by the attachment pipeline.
• lib/import-fresh.js - require wrapper that bypasses the module cache.
• lib/universal/check-if-conditions.mjs - ESM utility for evaluating conditional visibility rules in schemas; runs in both Node and browser.
• modules/@apostrophecms/ - All built-in content modules. Each sub-directory is a self-contained Apostrophe module with index.js, optional ui/src/, and optional views/.
• scripts/ - Database migration runners and build helpers; invoked by npm scripts.
• test-lib/ - Shared utilities for writing Apostrophe module tests (not for production).
• claude-tools/ - Diagnostic scripts for detecting event loop hangs and MongoDB connection leaks; not for production use.

Common pitfalls and fixes

• MongoDB not running at startup: Apostrophe exits immediately if it cannot connect. Fix: ensure APOS_MONGODB_URI points to a live instance before running node app.js.
• shortName collision across environments: Cookie names and session keys are prefixed with shortName. Two apps on the same domain with the same shortName will share sessions. Fix: use distinct shortName values per app.
• ESM/CJS interop with lib/universal/*.mjs: These files use .mjs extension and ES module syntax. If your bundler sees them, configure it to handle .mjs as ESM. In Node, require() cannot load .mjs; use dynamic import().
• Asset build hangs on first run: The Webpack/Vite asset pipeline runs synchronously on cold start. Fix: run node app.js once and wait; subsequent starts use cached bundles unless source changes.
• Cluster mode and hot-reload: cluster: true spawns multiple workers; file watchers (e.g., nodemon) may restart only the primary. Fix: disable clustering in development (NODE_ENV=development sets it off by default).
• Module extend resolution order: A module that extends another must be loaded after it. If you see "base class not found" errors, check that the extended module is listed or auto-discovered before the extender in your modules config.

Vibe-coding prompt template

I have the ApostropheCMS core source in ./source/ and its integration guide
in ./source/USAGE.md. The upstream package is `apostrophe`.

Please integrate ApostropheCMS into my existing Node.js project step by step:

1. Read USAGE.md and the file excerpts in source/index.js,
   source/modules/@apostrophecms/admin-bar/index.js, and
   source/modules/@apostrophecms/any-doc-type/index.js to understand the
   real API surface.

2. Create app.js that calls the apostrophe() factory with shortName,
   a MongoDB URI from process.env.APOS_MONGODB_URI, and the modules listed
   below: [YOUR MODULES HERE].

3. Add a custom piece type module named "article" that extends
   @apostrophecms/piece-type with title and body fields.

4. Register an admin bar button for the article manager using
   apos.adminBar.add() inside the article module's init() function.

5. Add a REST API route on the article module that queries all articles
   using self.find(req).toArray() and returns JSON.

6. Show me the final directory structure and all new/modified files.

Do not invent APIs. Only use methods and options visible in the file excerpts
and USAGE.md.

License and credit

ApostropheCMS is released under the MIT License (see source/LICENSE.md). The upstream project is maintained by the ApostropheCMS team at https://github.com/apostrophecms/apostrophe. Documentation is available at https://docs.apostrophecms.org/.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。