create-vitnode-app 1.2.0-canary.9 → 2.0.0-canary.2

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Maciej Piotr Balcerzak
+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

package/README.md

@@ -1,44 +1,84 @@
-# (VitNode) Create App
+# Create VitNode App
 
-This package is a CLI tool to create a new VitNode app quickly.
-
-Script based on [Create Next App](https://nextjs.org/).
+`create-vitnode-app` scaffolds a TanStack Start and Hono VitNode application,
+or an installable plugin for an existing VitNode workspace.
 
 <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">
+      <img alt="VitNode" src="https://raw.githubusercontent.com/VitNode/vitnode/canary/assets/logo/vitnode_logo_light.svg" width="400">
     </picture>
   </a>
-  <br>
-  <br>
 </p>
 
-## Usage
+## Create an app
+
+### Bun
 
 ```bash
-npx create-vitnode-app@latest
+bun create vitnode-app@latest
 ```
 
-or
+### pnpm
 
 ```bash
 pnpm create vitnode-app@latest
 ```
 
-or
+### npm
 
 ```bash
-bun create vitnode-app@latest
+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. Enable the
+feature by registering it in the host’s `vitnode.config.ts`:
+
+```ts
+import { myPlugin } from '@acme/my-plugin/config'
+
+plugins: [myPlugin()]
 ```
 
 ## Options
 
-| Option              | Description                                                |
-| ------------------- | ---------------------------------------------------------- |
-| `--package-manager` | Specify the package manager to use. Support `npm`, `pnpm`. |
-| `--eslint`          | Initialize with eslint config.                             |
-| `--skip-install`    | Skip installing packages after initializing the project.   |
+| 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,62 @@
+<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
+```
+
+## Configuration
+
+Two files, and the line between them is one question: may a browser hold this?
+
+| File                           | Holds                                                                                                                    |
+| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `src/vitnode.config.ts`        | locales, metadata, theme, `debug`, enabled plugin ids - plain data, read by the browser, the server, and your Vite build |
+| `src/vitnode.server.config.ts` | message loaders - server only                                                                                            |
+
+Add a language to `i18n.locales` in the shared config; register the files that
+translate it in `src/locales/packages.ts` (a package's own translations) or
+`src/locales/app.ts` (your rewordings). `pnpm vitnode i18n:create de Deutsch`
+does all three.
+
+`src/start.ts` is one call to `createVitNodeStart`, which installs CSRF
+protection for server functions, canonical locale redirects with the
+remembered-locale cookie, and the `private, no-store` directive every rendered
+document needs. Add your own request middleware with `requestMiddleware` - it
+runs after all of it.
+
+See [Configuration](https://vitnode.com/docs/dev/configuration).

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/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,57 @@
+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";
+
+config({
+  quiet: true,
+});
+
+export const POSTGRES_URL =
+  process.env.POSTGRES_URL ?? "postgresql://root:root@localhost:5432/vitnode";
+
+export const vitNodeApiConfig = buildApiConfig({
+  plugins: [],
+  /**
+   * The languages this installation serves.
+   *
+   * The API half of a split deployment. `apps/web/src/vitnode.config.ts`
+   * declares the same list, 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. Nothing walks the filesystem looking for the web app's
+   * config either - a bootstrap that guessed at a sibling application is exactly
+   * what that replaced, and it guessed wrong the moment the two were not laid
+   * out the way it expected.
+   *
+   * 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.
+   *
+   * Packages ship their own translations, so a new locale needs no `messages`
+   * entry - anything untranslated falls back to `defaultLocale` key by key.
+   */
+  i18n: {
+    defaultLocale: "en",
+    locales: [{ code: "en", name: "English" }],
+    /**
+     * Explicit, because this API renders emails on a server: without one, dates
+     * format in whatever zone the host happens to run in.
+     */
+    timeZone: "UTC",
+  },
+  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,36 @@
+import { buildApiConfig } from "@vitnode/core/vitnode.config";
+import { coreRelations } from "@vitnode/core/database/relations";
+import { drizzle } from "drizzle-orm/postgres-js";
+
+import { vitNodeConfig } from "./vitnode.config";
+
+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 site's own locale declaration, because this app is both: `vitnode.config.ts`
+   * is the one statement of which languages exist, and both configs read it.
+   *
+   * It is also what `vitnode db:prepare` seeds `core_languages` from - this app
+   * owns the schema - so adding a language there and re-running `dev` inserts
+   * its row. Leave it out and the seed falls back to `en` alone, whatever the
+   * site serves.
+   */
+  i18n: vitNodeConfig.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

@@ -1,4 +1,4 @@
-import vitnodePrettier from "eslint-config-typescript-vitnode/prettierrc";
+import vitnodePrettier from "@vitnode/config/prettierrc";
 
 /**
  * @see https://prettier.io/docs/en/configuration.html

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

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

package/copy-of-vitnode-app/{root → eslint-react}/.prettierrc.mjs

@@ -1,4 +1,4 @@
-import vitnodePrettier from "eslint-config-typescript-vitnode/prettierrc";
+import vitnodePrettier from "@vitnode/config/prettierrc";
 
 /**
  * @see https://prettier.io/docs/en/configuration.html

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