npm install --save-dev typescript @types/node @types/express \
  @types/cookie-parser @types/cors @types/express-session \
  @types/express-fileupload typescript-eslint @eslint/js \
  eslint-plugin-cypress globals cypress

No native build steps, iOS pods, or Android linking required. jimp is pure JavaScript; no native image binaries needed.

Project setup

1. Copy the source/ directory into your project root or a subdirectory (e.g., ./gathio/).
2. Copy source/config/config.example.toml to source/config/config.toml and fill in all required fields (MongoDB URI, SMTP/Sendgrid/Mailgun credentials, site URL, instance name).
3. Merge or reference source/tsconfig.json from your root tsconfig.json:

   {
     "extends": "./gathio/tsconfig.json",
     "include": ["src/**/*", "gathio/src/**/*"]
   }
   

4. Set the following environment variables (or configure via config.toml):

   export GATHIO_MONGO_URI="mongodb://localhost:27017/gathio"
   export GATHIO_SITE_URL="https://yourdomain.example"
   export GATHIO_INSTANCE_NAME="My Gathio"
   export GATHIO_MAIL_SERVICE="smtp"   # or "sendgrid" or "mailgun"
   export GATHIO_SMTP_HOST="smtp.example.com"
   export GATHIO_SMTP_PORT="587"
   export GATHIO_SMTP_USER="user@example.com"
   export GATHIO_SMTP_PASS="secret"
   

5. Install dependencies from source/package.json:

   cd source && npm install
   

6. Build and start:

   npm run build
   npm start
   # or with PM2: pm2 start ecosystem.config.cjs
   

7. For federation (ActivityPub), ensure your GATHIO_SITE_URL is publicly reachable over HTTPS and the /.well-known/webfinger route is not blocked by a reverse proxy.

Public API

The excerpts expose configuration-level and tooling-level symbols rather than a traditional exported library API. Below are the three concrete, documentable symbols visible in the file excerpts.

defineConfig (cypress.config.ts)

import { defineConfig } from "cypress";

const config = defineConfig({
  e2e: {
    baseUrl: string;
    setupNodeEvents?: (on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions) => void;
  };
});

Used to configure the Cypress e2e test runner. Set baseUrl to match the port your Gathio instance listens on before running npx cypress run.

tseslint.config (eslint.config.mjs)

import tseslint from "typescript-eslint";

const config = tseslint.config(
  ...configs: Linter.FlatConfig[]
): Linter.FlatConfig[];

Composes the flat ESLint configuration array. Gathio layers @eslint/js recommended, TypeScript-ESLint recommended, node globals, and Cypress plugin rules. Extend or override by appending additional config objects to the array.

globalIgnores (eslint.config.mjs)

import { globalIgnores } from "eslint/config";

globalIgnores(patterns: string[]): Linter.FlatConfig;

Returns a flat config entry that excludes matching paths from all ESLint rules. Gathio ignores dist/ and public/js/**/*.js; add your own build output paths here when integrating.

Working examples

Scenario - Running the Gathio server alongside an existing Express app

You have an existing Express app and want to mount Gathio's router under a /events prefix. Gathio's entry point is in src/; import it after building.

import express from "express";
import cookieParser from "cookie-parser";
import session from "express-session";
import cors from "cors";

// After building source/, the compiled entry is at dist/app.js (check package.json "main")
// Mount as a sub-application or use its router export if available.
const app = express();

app.use(cors({ origin: process.env.GATHIO_SITE_URL }));
app.use(cookieParser());
app.use(session({
  secret: process.env.SESSION_SECRET ?? "change-me",
  resave: false,
  saveUninitialized: false,
}));
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Serve Gathio static assets
app.use("/gathio/public", express.static("./gathio/public"));

// Start your own app; Gathio runs on its own port per ecosystem.config.cjs
app.listen(4000, () => console.log("Host app on 4000, Gathio on 3000"));

Scenario - Running Cypress e2e tests against a local Gathio instance

Start Gathio on port 3000, then run the suite. The cypress.config.ts baseUrl is already set correctly.

// cypress/support/commands.ts extension example
// Add a custom command to create a test event via the UI
Cypress.Commands.add("createEvent", (title: string) => {
  cy.visit("/new");
  cy.get('input[name="eventName"]').type(title);
  cy.get('input[name="eventLocation"]').type("Online");
  cy.get('input[name="eventStart"]').type("2025-12-01T18:00");
  cy.get('input[name="eventEnd"]').type("2025-12-01T20:00");
  cy.get('button[type="submit"]').click();
});

# Terminal 1
cd source && npm start

# Terminal 2
npx cypress run --spec "cypress/**/*.cy.ts"

Scenario - Linting the integrated source with the Gathio ESLint config

// eslint.config.mjs in your project root – extend Gathio's config
import { globalIgnores } from "eslint/config";
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";
import pluginCypress from "eslint-plugin-cypress/flat";
import globals from "globals";

export default tseslint.config(
  globalIgnores(["dist/", "public/js/**/*.js", "my-other-build/"]),
  eslint.configs.recommended,
  tseslint.configs.recommended,
  {
    languageOptions: {
      globals: { ...globals.node },
    },
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
    },
  },
  {
    files: ["cypress/**/*.ts"],
    plugins: { cypress: pluginCypress },
    ...pluginCypress.configs.recommended,
    rules: {
      "@typescript-eslint/no-unused-expressions": "off",
    },
  },
);

File walkthrough

• .github/ - GitHub Actions CI (test, lint) and GHCR container publish workflows.
• config/ - config.example.toml is the canonical reference for every configurable option; copy it to config.toml before starting.
• cypress/ - Cypress e2e tests with support commands and a dedicated tsconfig.json scoped to test files.
• docs/ - MkDocs Markdown documentation covering installation, configuration, customization, and ActivityPub federation.
• locales/ - JSON translation files loaded at runtime by i18next-fs-backend; add a new file to support additional languages.
• public/ - Pre-built CSS (Bootstrap), Font Awesome webfonts, and all static browser assets served directly.
• scripts/ - One-off database migration or maintenance scripts; not part of the main application boot.
• src/ - All application logic: Express routes, Mongoose models, ActivityPub federation handlers, email senders, Handlebars templates, and middleware.
• static/ - Additional static files (e.g., upload directory) referenced by the app at runtime.
• cypress.config.ts - Cypress runner configuration; sets baseUrl to http://localhost:3000.
• eslint.config.mjs - Flat ESLint config combining TypeScript-ESLint, node globals, and Cypress rules.
• ecosystem.config.cjs - PM2 application definition for production process management.
• tsconfig.json - TypeScript compiler options; check outDir and rootDir before merging into a monorepo.
• utils.ts - Root-level shared utilities imported across src/; currently minimal.
• docker-compose.yml - Compose stack for Gathio + MongoDB; usable for local development or production.
• mkdocs.yml - MkDocs site structure and theme configuration for the documentation site.

Common pitfalls and fixes

• MongoDB not running: Gathio will crash silently on startup if GATHIO_MONGO_URI is unreachable; ensure MongoDB is up before starting and check config.toml for the correct URI.
• Missing config.toml: The app reads config/config.toml at boot; if the file is absent it throws immediately. Always copy config.example.toml first.
• ActivityPub federation requires HTTPS: Webfinger and AP endpoints are rejected by remote servers over plain HTTP; use a reverse proxy (nginx/Caddy) with a valid TLS cert in production.
• jimp version mismatch: jimp must be the version pinned in package.json; major versions have breaking API changes. Do not upgrade without testing image upload and resize.
• ESM/CJS interop: eslint.config.mjs uses ESM (import); ecosystem.config.cjs uses CJS (require). Do not rename extensions or change "type" in package.json without updating both files.
• Cypress baseUrl: If you change Gathio's port (default 3000), update cypress.config.ts baseUrl accordingly or Cypress tests will time out with no useful error.

Vibe-coding prompt template

I have purchased the "gathio" source block. The source is in the `source/` directory.
There is an integration guide at `USAGE.md`. The upstream npm package is `user@example.com`.

Please help me integrate Gathio into my existing Node.js/TypeScript/Express project step by step:

1. Read `USAGE.md` and `source/config/config.example.toml` to understand all required configuration.
2. Copy and wire `source/src/` into my project, resolving any import path conflicts with my existing code.
3. Set up the environment variables listed in `USAGE.md` and create `source/config/config.toml` from the example.
4. Merge `source/tsconfig.json` with my root `tsconfig.json` without breaking either compilation target.
5. Extend `source/eslint.config.mjs` into my project's ESLint config using the flat config format shown in `USAGE.md`.
6. Show me how to run the Cypress e2e tests from `source/cypress/` against a locally running instance.
7. Explain any changes needed to serve `source/public/` static assets from my existing Express app.

Use only real exports and file paths visible in `source/` and `USAGE.md`. Do not invent APIs.

License and credit

See source/LICENSE for the full license terms. Gathio is developed by its contributors; the full list is at github.com/lowercasename/gathio. Upstream npm 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.