No native modules, pod installs, or Android linking are required. Node.js 18+ is recommended (the source uses import.meta.dirname and top-level ESM).

Project setup

1. Copy the source/ directory into your project root, e.g. ./ackee/.
2. Ensure your package.json includes "type": "module" — all source files use ESM syntax.
3. If you use TypeScript, add path aliases and allowImportingTsExtensions is not needed because the source is plain JS. Set "moduleResolution": "bundler" or "node16" and "allowJs": true in tsconfig.json.
4. Create a .env file (or export environment variables):

# Minimum required
MONGODB_URI=mongodb://localhost:27017/ackee
PORT=3000

# Optional
ACKEE_USERNAME=admin
ACKEE_PASSWORD=secret
ACKEE_ALLOW_ORIGIN=https://yoursite.com
ACKEE_TRACKER=custom
NODE_ENV=development   # enables isDevelopmentMode
ACKEE_DEMO=true        # enables isDemoMode (read-only)

5. The utils/config.js module reads process.env directly; no additional config file is needed.
6. Run the entry point:

node ackee/index.js

For serverless targets (Vercel/Netlify), export the handler from ackee/serverless.js instead.

Public API

server

import server from './ackee/server.js'
// server: http.Server (Express + Apollo integrated)

The configured HTTP server. Attach listening and error event listeners, then call server.listen(port). Used by index.js after the MongoDB connection is established. Import directly when you want to embed Ackee's server into an existing process manager.

connect

import connect from './ackee/utils/connect.js'
// connect(dbUrl: string): Promise<typeof mongoose>

Establishes the Mongoose connection to MongoDB. Must be awaited before calling server.listen(). Returns the mongoose instance; throws on connection failure.

ui.index / ui.styles / ui.scripts / ui.tracker / ui.build

import { index, styles, scripts, tracker, build } from './ackee/ui/index.js'

index(): string                        // returns the HTML shell string
styles(): Promise<string>              // compiles SCSS to CSS
scripts(): Promise<string>             // bundles frontend JS
tracker(): Promise<string>             // reads ackee-tracker client bundle
build(outputPath: string, fn: () => Promise<string>): Promise<void>

These functions generate and optionally write the UI assets to disk. build is used at startup or in a pre-build step to emit static files. Call styles() and scripts() only when optional peer dependencies rosid-handler-sass and rosid-handler-js-next are installed.

Working examples

Scenario - Standalone server startup

Start the Ackee HTTP server after connecting to MongoDB, mirroring what index.js does, but embedded inside your own startup sequence.

// src/startAckee.ts
import server from './ackee/server.js'
import connect from './ackee/utils/connect.js'

const DB_URL = process.env.MONGODB_URI ?? 'mongodb://localhost:27017/ackee'
const PORT = Number(process.env.PORT ?? 3000)

export async function startAckee(): Promise<void> {
  await connect(DB_URL)

  await new Promise<void>((resolve, reject) => {
    server.on('error', reject)
    server.listen(PORT, () => {
      console.log(`Ackee listening on http://localhost:${PORT}`)
      resolve()
    })
  })
}

Scenario - Serverless deployment (Vercel / Netlify)

Use the pre-wired serverless export so you do not need to manage the HTTP server lifecycle.

// api/analytics.ts  (Vercel Edge/Serverless function)
// Vercel expects a default export that is a request handler
export { default } from '../ackee/serverless.js'

In vercel.json:

{
  "functions": {
    "api/analytics.ts": { "memory": 512 }
  },
  "env": {
    "MONGODB_URI": "@mongodb_uri",
    "ACKEE_USERNAME": "@ackee_username",
    "ACKEE_PASSWORD": "@ackee_password"
  }
}

Scenario - Pre-building static UI assets

Write compiled CSS and JS to a dist/ folder during your CI build step so the server can serve them as static files.

// scripts/buildUi.ts
import path from 'node:path'
import { styles, scripts, tracker, build } from './ackee/ui/index.js'

await build(path.resolve('dist/index.css'), styles)
await build(path.resolve('dist/index.js'), scripts)
await build(path.resolve('dist/tracker.js'), tracker)
console.log('UI assets written to dist/')

Run with: node --loader ts-node/esm scripts/buildUi.ts

File walkthrough

• index.js - Entry point: validates env, connects Mongoose, starts server.listen.
• server.js - Constructs the Express app, mounts Apollo Server middleware and UI routes.
• serverless.js - Wraps the Express app for serverless function environments.
• healthcheck.js - Fires an HTTP GET to localhost:{PORT}/ and exits 0/1; used by Docker HEALTHCHECK.
• resolvers/index.js - Merges all entity resolvers into one resolver map via @graphql-tools/merge.
• types/index.js - Merges all GraphQL SDL type-def modules into a single DocumentNode.
• aggregations/ - Each file runs a MongoDB aggregation pipeline and returns computed stats (views, actions, durations, active visitors, top records).
• constants/ - Pure value exports (arrays/objects) for browsers, devices, intervals, ranges, sortings, referrers, sizes, systems, views.
• database/ - Thin async functions wrapping Mongoose queries for each collection; called by resolvers.
• middlewares/ - requireAuth validates Bearer tokens; blockDemoMode returns 403 in demo mode.
• models/ - Mongoose schemas and model constructors for Action, Domain, Event, PermanentToken, Record, Token.
• stages/ - Helper functions returning MongoDB aggregation stage objects (match, limit, project).
• ui/ - Server-side asset pipeline plus the React frontend application under ui/scripts/.
• utils/ - Config reader, Mongoose connector, signale logger instance, URL sanitization helpers, HTML layout generator.

Common pitfalls and fixes

• "type": "module" missing: All source files use bare ESM import; without this in package.json Node.js will throw SyntaxError. Fix: add "type": "module" to your package.json.
• MONGODB_URI not set: index.js calls process.exit(1) immediately if config.dbUrl is null. Fix: ensure the env var is exported before the process starts or loaded via a .env file using a package like dotenv loaded before import.
• rosid-handler-sass / rosid-handler-js-next not installed: ui.styles() and ui.scripts() do a dynamic import() of these packages; they are not listed in package.json because they are optional build-time deps. Fix: npm install rosid-handler-sass rosid-handler-js-next if you want server-side asset compilation.
• Apollo Server v4 breaking change: This source uses @apollo/server v4 with @as-integrations/express5. Do not mix with apollo-server-express v2/v3 APIs. Fix: use @as-integrations/express5 exactly as imported in server.js.
• ESM / CommonJS interop with signale: signale ships CJS; if bundlers complain, add "signale" to esmExternals or use createRequire. Fix: the source already handles this internally; do not re-export signale through a CJS wrapper.
• import.meta.dirname requires Node 20.11+: ui/index.js uses import.meta.dirname. Fix: upgrade to Node 20.11+ or polyfill with const __dirname = new URL('.', import.meta.url).pathname.

Vibe-coding prompt template

I have the Ackee analytics server source checked out at `./ackee/` inside my
project, and a usage guide at `./USAGE.md`. The upstream package is `user@example.com`.

Please help me integrate it into my existing Node.js project step-by-step:

1. Read `USAGE.md` fully before writing any code.
2. Identify which files in `./ackee/` I need to import for my goal: [describe goal, e.g. "embed the GraphQL API into my existing Express app"].
3. Show me the exact imports using the real exported symbols documented in USAGE.md.
4. Write runnable ESM TypeScript/JavaScript code that wires the Ackee server (or the specific modules I need) into my existing `src/app.ts`.
5. List any additional environment variables I must set.
6. Point out any dependency version conflicts with my current `package.json`.
7. Do not invent any API names; only use symbols present in `USAGE.md` or directly visible in the source files under `./ackee/`.

License and credit

Ackee is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository for the full license text.

Upstream project: Ackee on GitHub - package user@example.com.

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

The full install guide and integration prompts unlock after purchase.