create-vitnode-app 0.0.1-canary.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 aXenDev Maciej Balcerzak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Create VitNode App
+
+`create-vitnode-app` scaffolds a TanStack Start and Hono VitNode application,
+or an installable plugin for an existing VitNode workspace.
+
+<p align="center">
+  <a href="https://vitnode.com/" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_light.svg">
+      <img alt="VitNode" src="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_light.svg" width="400">
+    </picture>
+  </a>
+</p>
+
+## Create an app
+
+### Bun
+
+```bash
+bun create vitnode-app@latest
+```
+
+### pnpm
+
+```bash
+pnpm create vitnode-app@latest
+```
+
+### npm
+
+```bash
+npm create vitnode-app@latest
+```
+
+Choose Turborepo during setup if you will build plugins. It gives your project a
+workspace root and a `plugins/*` home.
+
+## Create a plugin
+
+Run this from an existing VitNode workspace, then enter the plugin package name
+when prompted:
+
+### Bun
+
+```bash
+bun create vitnode-app@latest --plugin
+```
+
+### pnpm
+
+```bash
+pnpm create vitnode-app@latest --plugin
+```
+
+### npm
+
+```bash
+npm create vitnode-app@latest -- --plugin
+```
+
+The generator creates the package and adds its workspace dependency. Register it
+in the host’s `vitnode.config.ts` to enable the feature.
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `--package-manager` | Choose `npm` or `pnpm` for the generated project. |
+| `--eslint` | Include ESLint and Prettier configuration. |
+| `--skip-install` | Skip dependency installation after scaffolding. |
+| `--mode` | Choose `singleApp`, `apiMonorepo`, or `onlyApi`. |
+| `--monorepo` | Create a workspace layout for plugins and multiple applications. |
+| `--docker` | Include local Docker services. |
+| `--plugin` | Create a VitNode plugin package. |
+
+Read the [VitNode documentation](https://vitnode.com/docs/dev) for setup,
+plugins, deployment, and AdminCP guides.

package/copy-of-vitnode-app/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "cSpell.words": [
+    "vitnode"
+  ],
+  "github.copilot.chat.commitMessageGeneration.instructions": [
+    {
+      "text": "Follow the Conventional Commits format strictly for commit messages. Use the structure below:\n\n```\n<type>[optional scope]: <gitmoji> <description>\n```\n\nGuidelines:\n\n1. **Type and Scope**: Choose an appropriate type (e.g., `feat`, `fix`, `refactor`, `docs`) and optional scope to describe the affected module or feature.\n\n2. **Gitmoji**: Include a relevant `gitmoji` that best represents the nature of the change.\n\n3. **Description**: Write a concise, informative description in the header; use backticks if referencing code or specific terms.\n\nCommit messages should be clear, informative, and professional, aiding readability and project tracking."
+    }
+  ]
+}

package/copy-of-vitnode-app/README.md

@@ -0,0 +1,40 @@
+<p align="center">
+  <br>
+  <a href="https://vitnode.com/" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_light.svg">
+      <img alt="VitNode Logo" src="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_light.svg" width="400">
+    </picture>
+  </a>
+  <br>
+  <br>
+</p>
+
+# VitNode App
+
+This is a basic template for a [VitNode](https://vitnode.com/) app.
+
+## Getting Started
+
+To get started, run the following commands:
+
+```bash
+pnpm i
+```
+
+Open {{START_URLS}} with your browser to see the result.
+
+## Development
+
+To start the development server, you need to create a `.env` file from the provided `.env.example` file.
+
+In the `development` environment, you can just copy and paste the content of `.env.example` to `.env`.
+
+### Development server
+
+To start the development server, run the following command:
+
+```bash
+pnpm dev
+```

package/copy-of-vitnode-app/api/.gitignore_template

@@ -0,0 +1,32 @@
+# Dependencies
+node_modules
+
+# Turbo
+.turbo
+
+# Test & Build
+/coverage
+/desc
+*.tsbuildinfo
+
+# Misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Others
+.vercel
+
+# Local storage adapter uploads
+/public/uploads

package/copy-of-vitnode-app/api/drizzle.config.ts

@@ -0,0 +1,12 @@
+import { defineVitNodeDrizzleConfig } from "@vitnode/core/drizzle.config";
+
+import { POSTGRES_URL, vitNodeApiConfig } from "./src/vitnode.api.config";
+
+export default defineVitNodeDrizzleConfig({
+  vitNodeApiConfig,
+  out: "./migrations/",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: POSTGRES_URL,
+  },
+});

package/copy-of-vitnode-app/api/src/i18n.ts

@@ -0,0 +1,38 @@
+import type { VitNodeI18nConfig } from "@vitnode/core/lib/i18n/types";
+
+/**
+ * The languages this installation serves.
+ *
+ * The API half of a split deployment. `apps/web` has a file of the same name,
+ * and the two are one declaration in two places by necessity rather than by
+ * design: they are separate packages, so neither can import the other's.
+ *
+ * They have to agree, and this is the copy that matters most - this app owns the
+ * schema, so `vitnode db:prepare` seeds `core_languages` from *this* list. A
+ * language that is here and not in the web app's renders nowhere; one that is in
+ * the web app's and not here has no row in the database, and everything keyed on
+ * a language row has nowhere to put it.
+ *
+ * Deliberately not discovered: nothing walks the filesystem looking for the web
+ * app's config. A bootstrap that guessed at a sibling application is exactly
+ * what this replaced, and it guessed wrong the moment the two were not laid out
+ * the way it expected.
+ *
+ * Packages ship their own translations, so a new locale needs no `messages`
+ * entry - anything untranslated falls back to `defaultLocale` key by key.
+ */
+export const i18n = {
+  defaultLocale: "en",
+  /**
+   * Explicit, because this API renders emails on a server: without one, dates
+   * format in whatever zone the host happens to run in.
+   */
+  timeZone: "UTC",
+  locales: [
+    {
+      code: "en",
+      name: "English",
+    },
+  ],
+  messages: {},
+} satisfies VitNodeI18nConfig;

package/copy-of-vitnode-app/api/src/index.ts

@@ -0,0 +1,27 @@
+import { serve } from "@hono/node-server";
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { VitNodeAPI } from "@vitnode/core/api/config";
+
+import { vitNodeApiConfig } from "./vitnode.api.config.js";
+
+const app = new OpenAPIHono().basePath("/api");
+
+VitNodeAPI({
+  app,
+  vitNodeApiConfig,
+});
+
+serve(
+  {
+    fetch: app.fetch,
+    port: 8000,
+  },
+  info => {
+    const initMessage = "\x1b[34m[VitNode]\x1b[0m";
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `${initMessage} API server is running on http://localhost:${info.port}`,
+    );
+  },
+);

package/copy-of-vitnode-app/api/src/vitnode.api.config.ts

@@ -0,0 +1,40 @@
+import { buildApiConfig } from "@vitnode/core/vitnode.config";
+import { config } from "dotenv";
+import { coreRelations } from "@vitnode/core/database/relations";
+import { drizzle } from "drizzle-orm/postgres-js";
+
+import { i18n } from "./i18n.js";
+
+config({
+  quiet: true,
+});
+
+export const POSTGRES_URL =
+  process.env.POSTGRES_URL ?? "postgresql://root:root@localhost:5432/vitnode";
+
+export const vitNodeApiConfig = buildApiConfig({
+  plugins: [],
+  /**
+   * The installation's languages - see `src/i18n.ts`, and keep it in step with
+   * the web app's file of the same name.
+   *
+   * This app owns the schema, so `vitnode db:prepare` seeds `core_languages`
+   * from this list. Leave it out and the seed falls back to `en` alone, whatever
+   * the site serves.
+   */
+  i18n,
+  dbProvider: drizzle({
+    connection: POSTGRES_URL,
+    relations: coreRelations,
+  }),
+  // Redis is opt-in: only enabled when REDIS_URL is set. Without it the cache
+  // is a no-op, the rate limiter uses in-memory storage, and WebSockets run in
+  // single-instance mode.
+  redis: process.env.REDIS_URL
+    ? { url: process.env.REDIS_URL, password: process.env.REDIS_PASSWORD }
+    : undefined,
+  metadata: {
+    title: "VitNode API",
+    shortTitle: "VitNode",
+  },
+});

package/copy-of-vitnode-app/api/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@vitnode/config/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "rootDir": "./",
+    "outDir": "./dist",
+    "incremental": false,
+    "types": ["node"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "global.d.ts"],
+  "exclude": ["node_modules"]
+}

package/copy-of-vitnode-app/api-bun/src/index.ts

@@ -0,0 +1,16 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { VitNodeAPI } from "@vitnode/core/api/config";
+
+import { vitNodeApiConfig } from "./vitnode.api.config.js";
+
+const app = new OpenAPIHono().basePath("/api");
+
+VitNodeAPI({
+  app,
+  vitNodeApiConfig,
+});
+
+export default {
+  port: 8000,
+  fetch: app.fetch,
+};

package/copy-of-vitnode-app/api-single-app/drizzle.config.ts

@@ -0,0 +1,12 @@
+import { defineVitNodeDrizzleConfig } from "@vitnode/core/drizzle.config";
+
+import { POSTGRES_URL, vitNodeApiConfig } from "./src/vitnode.api.config";
+
+export default defineVitNodeDrizzleConfig({
+  vitNodeApiConfig,
+  out: "./migrations/",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: POSTGRES_URL,
+  },
+});

package/copy-of-vitnode-app/api-single-app/src/routes/api/$.ts

@@ -0,0 +1,32 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+import { apiBridge } from '#/server/vitnode-api.server'
+
+/**
+ * `/api/*` - the existing VitNode Hono application, mounted.
+ *
+ * `server` is the only option on this route on purpose. TanStack Start prunes a
+ * route file whose sole option is `server` out of the client route tree
+ * entirely (and its client code-splitter deletes the `server` node on top of
+ * that), so none of the API - Hono, Drizzle, the plugins - can reach the browser
+ * bundle. The `.server.ts` import is refused by import protection if that ever
+ * stops being true.
+ *
+ * `ANY` rather than a handler per method: routing, OpenAPI, middleware, auth,
+ * plugin mounting and error handling all stay inside Hono, exactly as they are
+ * when the same app runs standalone in `apps/api` or under the Next.js catch-all
+ * in `apps/docs`. `ANY` is part of the framework's `RouteMethod` union and is
+ * what Start falls back to for any method it was given no handler for - `HEAD`
+ * included, where it calls this handler and strips the response body itself.
+ * So the API keeps answering for methods this file has never heard of, which is
+ * the point: there is nothing here to keep in sync with the API's routes.
+ *
+ * `src/tests/api-server-route.test.ts` drives the real request handler over this
+ * route to hold that to every method the API needs.
+ */
+export const Route = createFileRoute('/api/$')({
+  server: {
+    handlers: ({ createHandlers }) =>
+      createHandlers({ ANY: async ({ request }) => apiBridge(request) }),
+  },
+})

package/copy-of-vitnode-app/api-single-app/src/server/api-bridge.ts

@@ -0,0 +1,22 @@
+/**
+ * The seam between the web runtime and the Hono API.
+ *
+ * A bridge is handed the `Request` the browser (or an SSR loader) made to
+ * `/api/*` on this origin and answers it with whatever Hono answers. It is one
+ * line, and that is the point: status, body, every `Set-Cookie`, the cookie and
+ * `x-forwarded-*` headers the API reads are all already correct on the request
+ * the platform built, and stay correct exactly as long as nobody rebuilds them.
+ *
+ * `src/tests/api-bridge-contract.ts` holds this to that behaviour, including the
+ * ways a rebuilt request loses it.
+ */
+export type ApiBridge = (request: Request) => Promise<Response> | Response
+
+interface FetchableApp {
+  fetch: (request: Request) => Promise<Response> | Response
+}
+
+export const createApiBridge =
+  (app: FetchableApp): ApiBridge =>
+  async (request) =>
+    app.fetch(request)

package/copy-of-vitnode-app/api-single-app/src/server/vitnode-api.server.ts

@@ -0,0 +1,29 @@
+import '@tanstack/react-start/server-only'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { VitNodeAPI } from '@vitnode/core/api/config'
+
+import { createApiBridge } from '#/server/api-bridge'
+import { vitNodeApiConfig } from '#/vitnode.api.config'
+
+// The same two lines `apps/api` and `apps/docs` run. `basePath("/api")` is what
+// makes the mount point part of the API's own routing, so every path the plugins
+// register - `/api/@vitnode/core/...` - resolves identically here.
+const createVitNodeApi = () => {
+  const app = new OpenAPIHono().basePath('/api')
+
+  VitNodeAPI({ app, vitNodeApiConfig })
+
+  return app
+}
+
+// `VitNodeAPI` is a boot step, not a request step: it opens the Redis client,
+// starts the cron scheduler and registers every plugin route. Vite re-evaluates
+// server modules on HMR, so the instance is parked on `globalThis` to keep one
+// API per process instead of one per edit.
+const cache = globalThis as typeof globalThis & {
+  __vitnodeApi?: ReturnType<typeof createVitNodeApi>
+}
+
+export const vitNodeApi = (cache.__vitnodeApi ??= createVitNodeApi())
+
+export const apiBridge = createApiBridge(vitNodeApi)

package/copy-of-vitnode-app/api-single-app/src/vitnode.api.config.ts

@@ -0,0 +1,37 @@
+import { buildApiConfig } from "@vitnode/core/vitnode.config";
+import { coreRelations } from "@vitnode/core/database/relations";
+import { drizzle } from "drizzle-orm/postgres-js";
+
+import { i18n } from "./i18n";
+
+export const POSTGRES_URL =
+  process.env.POSTGRES_URL ?? "postgresql://root:root@localhost:5432/vitnode";
+
+export const vitNodeApiConfig = buildApiConfig({
+  metadata: {
+    title: "VitNode",
+    shortTitle: "VitNode",
+  },
+  plugins: [],
+  /**
+   * The same `src/i18n.ts` the frontend config reads, because this app is both:
+   * one declaration of which languages exist, spread into `buildConfig` through
+   * `vitnode.shell.config.ts` and passed here.
+   *
+   * It is also what `vitnode db:prepare` seeds `core_languages` from - this app
+   * owns the schema - so adding a language here and re-running `dev` inserts its
+   * row. Leave it out and the seed falls back to `en` alone, whatever the site
+   * serves.
+   */
+  i18n,
+  dbProvider: drizzle({
+    connection: POSTGRES_URL,
+    relations: coreRelations,
+  }),
+  // Redis is opt-in: only enabled when REDIS_URL is set. Without it the cache
+  // is a no-op, the rate limiter uses in-memory storage, and WebSockets run in
+  // single-instance mode.
+  redis: process.env.REDIS_URL
+    ? { url: process.env.REDIS_URL, password: process.env.REDIS_PASSWORD }
+    : undefined,
+});

package/copy-of-vitnode-app/docker/docker-compose.yml

@@ -0,0 +1,30 @@
+version: '3.8'
+
+services:
+  database:
+    container_name: vitnode_postgres_dev
+    image: postgres:17.5-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER-root}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD-root}
+      POSTGRES_DB: ${POSTGRES_NAME-vitnode}
+    volumes:
+      - ./docker/dev:/var/lib/postgresql/data
+    ports:
+      - '5432:5432'
+    networks:
+      - vitnode_dev
+
+  cache:
+    container_name: vitnode_redis_dev
+    image: redis:8.8-alpine
+    restart: unless-stopped
+    command: redis-server --requirepass ${REDIS_PASSWORD-root}
+    ports:
+      - '6379:6379'
+    networks:
+      - vitnode_dev
+
+networks:
+  vitnode_dev:

package/copy-of-vitnode-app/eslint/.prettierrc.mjs

@@ -0,0 +1,11 @@
+import vitnodePrettier from "@vitnode/config/prettierrc";
+
+/**
+ * @see https://prettier.io/docs/en/configuration.html
+ * @type {import("prettier").Config}
+ */
+const config = {
+  ...vitnodePrettier,
+};
+
+export default config;

package/copy-of-vitnode-app/eslint/eslint.config.mjs

@@ -0,0 +1,19 @@
+import eslintVitNode from "@vitnode/config/eslint";
+import eslintVitNodeReact from "@vitnode/config/eslint.react";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default [
+  ...eslintVitNode,
+  ...eslintVitNodeReact,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: __dirname,
+      },
+    },
+  },
+];

package/copy-of-vitnode-app/eslint-react/.prettierrc.mjs

@@ -0,0 +1,11 @@
+import vitnodePrettier from "@vitnode/config/prettierrc";
+
+/**
+ * @see https://prettier.io/docs/en/configuration.html
+ * @type {import("prettier").Config}
+ */
+const config = {
+  ...vitnodePrettier,
+};
+
+export default config;

package/copy-of-vitnode-app/eslint-react/eslint.config.mjs

@@ -0,0 +1,19 @@
+import eslintVitNode from "@vitnode/config/eslint";
+import eslintVitNodeReact from "@vitnode/config/eslint.react";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default [
+  ...eslintVitNode,
+  ...eslintVitNodeReact,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: __dirname,
+      },
+    },
+  },
+];

package/copy-of-vitnode-app/monorepo/.gitignore_template

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Testing
+coverage
+
+# Turbo
+.turbo
+
+# Vercel
+.vercel
+
+# Build Outputs
+.output/
+out/
+build
+dist
+
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Misc
+.DS_Store
+*.pem
+
+# VitNode
+/docker

package/copy-of-vitnode-app/monorepo/apps/api/.env.example

@@ -0,0 +1,12 @@
+POSTGRES_URL=postgresql://root:root@localhost:5432/vitnode
+REDIS_URL=redis://localhost:6379
+
+NEXT_PUBLIC_WEB_URL=http://localhost:3000
+
+# === Docker Database Postgres ===
+POSTGRES_USER=root
+POSTGRES_PASSWORD=root
+POSTGRES_NAME=vitnode
+
+# === Docker Redis ===
+REDIS_PASSWORD=root

package/copy-of-vitnode-app/monorepo/apps/web/.env.example

@@ -0,0 +1,12 @@
+NEXT_PUBLIC_API_URL=http://localhost:8000
+
+# Optional. Set these to back the Next.js caches with Redis, so cached pages and
+# `use cache` entries are shared between instances and a tag revalidation on one
+# instance is seen by all of them.
+#
+# The web process needs its own copy: the cache handlers are loaded by Next.js
+# itself and read the environment directly - they cannot see the API's
+# `vitnode.api.config.ts`. Point them at the same Redis the API uses.
+# https://vitnode.com/docs/dev/advanced/redis#caching-nextjs-output
+# REDIS_URL=redis://localhost:6379
+# REDIS_PASSWORD=root