feat: turbostarter boilerplate

Production-ready Next.js boilerplate with:
- Runtime env validation (fail-fast on missing vars)
- Feature-gated config (S3, Stripe, email, OAuth)
- Docker + Coolify deployment pipeline
- PostgreSQL + pgvector, MinIO S3, Better Auth
- TypeScript strict mode (no ignoreBuildErrors)
- i18n (en/es), AI modules, billing, monitoring

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
2026-02-02 17:29:12 +00:00
commit 3527e732d4
1618 changed files with 338230 additions and 0 deletions

View File

@@ -0,0 +1,37 @@
{
"name": "@turbostarter/eslint-config",
"version": "0.1.0",
"private": true,
"type": "module",
"exports": {
"./base": "./src/base.js",
"./next": "./src/next.js",
"./react": "./src/react.js"
},
"scripts": {
"clean": "git clean -xdf .cache .turbo node_modules",
"format": "prettier --check . --ignore-path ../../.gitignore",
"typecheck": "tsc --noEmit"
},
"prettier": "@turbostarter/prettier-config",
"dependencies": {
"@eslint/compat": "^1.4.1",
"@next/eslint-plugin-next": "16.0.10",
"@tanstack/eslint-plugin-query": "5.91.2",
"eslint-plugin-i18next": "6.1.3",
"eslint-plugin-import": "^2.32.0",
"eslint-plugin-jsx-a11y": "^6.10.2",
"eslint-plugin-react": "^7.37.5",
"eslint-plugin-react-hooks": "^5.2.0",
"eslint-plugin-turbo": "^2.6.0",
"eslint-plugin-unused-imports": "4.3.0",
"typescript-eslint": "^8.46.2"
},
"devDependencies": {
"@turbostarter/prettier-config": "workspace:*",
"@turbostarter/tsconfig": "workspace:*",
"eslint": "catalog:",
"prettier": "catalog:",
"typescript": "catalog:"
}
}

130
tooling/eslint/src/base.js Normal file
View File

@@ -0,0 +1,130 @@
/// <reference types="../types.d.ts" />
import * as path from "node:path";
import { fileURLToPath } from "node:url";
import { includeIgnoreFile } from "@eslint/compat";
import eslint from "@eslint/js";
import importPlugin from "eslint-plugin-import";
import turboPlugin from "eslint-plugin-turbo";
import unusedImportsPlugin from "eslint-plugin-unused-imports";
import tseslint from "typescript-eslint";
import i18nextPlugin from "eslint-plugin-i18next";
import { defineConfig } from "eslint/config";
const restrictEnvAccess = defineConfig({
files: ["**/*.js", "**/*.ts", "**/*.tsx"],
ignores: ["**/env*.ts"],
rules: {
"no-restricted-properties": [
"error",
{
object: "process",
property: "env",
message:
"Use `import { env } from 'env.config'` instead to ensure validated types.",
},
],
"no-restricted-imports": [
"error",
{
name: "process",
importNames: ["env"],
message:
"Use `import { env } from 'env.config'` instead to ensure validated types.",
},
],
},
});
export default defineConfig(
// Ignore files not tracked by VCS and any config files
includeIgnoreFile(
path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
"../../../.gitignore",
),
),
{ ignores: ["**/*.config.*"] },
{
files: ["**/*.js", "**/*.ts", "**/*.tsx"],
plugins: {
import: importPlugin,
"unused-imports": unusedImportsPlugin,
turbo: turboPlugin,
},
extends: [
eslint.configs.recommended,
i18nextPlugin.configs["flat/recommended"],
...tseslint.configs.recommended,
...tseslint.configs.recommendedTypeChecked,
...tseslint.configs.stylisticTypeChecked,
],
rules: {
...turboPlugin.configs.recommended.rules,
"@typescript-eslint/no-unused-vars": "off",
"@typescript-eslint/consistent-type-imports": [
"warn",
{ prefer: "type-imports", fixStyle: "separate-type-imports" },
],
"@typescript-eslint/no-misused-promises": [
2,
{ checksVoidReturn: { attributes: false } },
],
"@typescript-eslint/no-unnecessary-condition": [
"error",
{
allowConstantLoopConditions: true,
},
],
"import/consistent-type-specifier-style": ["error", "prefer-top-level"],
"import/order": [
"error",
{
alphabetize: {
caseInsensitive: true,
order: "asc",
},
pathGroups: [
{
pattern: "@turbostarter/**",
group: "internal",
position: "before",
},
{
pattern: "~/**",
group: "internal",
position: "before",
},
],
groups: [
["builtin", "external"],
"internal",
"parent",
"sibling",
"index",
"object",
"type",
],
"newlines-between": "always",
warnOnUnassignedImports: true,
pathGroupsExcludedImportTypes: ["type"],
},
],
"unused-imports/no-unused-imports": "error",
"unused-imports/no-unused-vars": [
"warn",
{
vars: "all",
varsIgnorePattern: "^_",
args: "after-used",
argsIgnorePattern: "^_",
},
],
},
},
{
linterOptions: { reportUnusedDisableDirectives: true },
languageOptions: { parserOptions: { projectService: true } },
},
restrictEnvAccess,
);

View File

@@ -0,0 +1,16 @@
import nextPlugin from "@next/eslint-plugin-next";
/** @type {Awaited<import('typescript-eslint').Config>} */
export default [
{
files: ["**/*.ts", "**/*.tsx"],
plugins: {
"@next/next": nextPlugin,
},
rules: {
...nextPlugin.configs.recommended.rules,
...nextPlugin.configs["core-web-vitals"].rules,
"@next/next/no-duplicate-head": "off",
},
},
];

25
tooling/eslint/src/react.js vendored Normal file
View File

@@ -0,0 +1,25 @@
import reactPlugin from "eslint-plugin-react";
import hooksPlugin from "eslint-plugin-react-hooks";
import queryPlugin from "@tanstack/eslint-plugin-query";
/** @type {Awaited<import('typescript-eslint').Config>} */
export default [
{
files: ["**/*.ts", "**/*.tsx"],
plugins: {
react: reactPlugin,
"react-hooks": hooksPlugin,
"@tanstack/query": queryPlugin,
},
rules: {
...reactPlugin.configs["jsx-runtime"].rules,
...hooksPlugin.configs.recommended.rules,
...queryPlugin.configs.recommended.rules,
},
languageOptions: {
globals: {
React: "writable",
},
},
},
];

View File

@@ -0,0 +1,5 @@
{
"extends": "@turbostarter/tsconfig/base.json",
"include": ["."],
"exclude": ["node_modules"]
}

76
tooling/eslint/types.d.ts vendored Normal file
View File

@@ -0,0 +1,76 @@
/**
* Since the ecosystem hasn't fully migrated to ESLint's new FlatConfig system yet,
* we "need" to type some of the plugins manually :(
*/
declare module "@eslint/js" {
// Why the hell doesn't eslint themselves export their types?
import type { Linter } from "eslint";
export const configs: {
readonly recommended: { readonly rules: Readonly<Linter.RulesRecord> };
readonly all: { readonly rules: Readonly<Linter.RulesRecord> };
};
}
declare module "eslint-plugin-import" {
import type { Linter, Rule } from "eslint";
export const configs: {
recommended: { rules: Linter.RulesRecord };
};
export const rules: Record<string, Rule.RuleModule>;
}
declare module "eslint-plugin-react" {
import type { Linter, Rule } from "eslint";
export const configs: {
recommended: { rules: Linter.RulesRecord };
all: { rules: Linter.RulesRecord };
"jsx-runtime": { rules: Linter.RulesRecord };
};
export const rules: Record<string, Rule.RuleModule>;
}
declare module "eslint-plugin-react-hooks" {
import type { Linter, Rule } from "eslint";
export const configs: {
recommended: {
rules: {
"rules-of-hooks": Linter.RuleEntry;
"exhaustive-deps": Linter.RuleEntry;
};
};
};
export const rules: Record<string, Rule.RuleModule>;
}
declare module "@next/eslint-plugin-next" {
import type { Linter, Rule } from "eslint";
export const configs: {
recommended: { rules: Linter.RulesRecord };
"core-web-vitals": { rules: Linter.RulesRecord };
};
export const rules: Record<string, Rule.RuleModule>;
}
declare module "eslint-plugin-turbo" {
import type { Linter, Rule } from "eslint";
export const configs: {
recommended: { rules: Linter.RulesRecord };
};
export const rules: Record<string, Rule.RuleModule>;
}
declare module "eslint-plugin-i18next" {
import type { Linter, Rule } from "eslint";
export const configs: {
"flat/recommended": { rules: Linter.RulesRecord };
};
export const rules: Record<string, Rule.RuleModule>;
}

View File

@@ -0,0 +1,3 @@
{
"name": "@turbostarter/github"
}

View File

@@ -0,0 +1,32 @@
name: CI / Setup
description: Common setup steps for Github Actions
inputs:
node-version:
description: "Node.js version"
required: true
default: "22.x"
install-packages:
description: "Install packages"
required: false
default: "true"
runs:
using: "composite"
steps:
- name: ✅ Checkout code
uses: actions/checkout@v5
- name: 🎬 Setup pnpm
uses: pnpm/action-setup@v4
- name: 🔨 Setup Node.js ${{ inputs.node-version }}
uses: actions/setup-node@v6
with:
node-version: ${{ inputs.node-version }}
cache: "pnpm"
- name: 🔌 Install
if: ${{ inputs.install-packages == 'true' }}
shell: bash
run: pnpm install

29
tooling/prettier/index.js Normal file
View File

@@ -0,0 +1,29 @@
/** @typedef {import("prettier").Config} PrettierConfig */
/** @typedef {import("prettier-plugin-tailwindcss").PluginOptions} TailwindConfig */
/** @type { PrettierConfig | TailwindConfig } */
const config = {
singleQuote: false,
trailingComma: "all",
tabWidth: 2,
useTabs: false,
printWidth: 80,
plugins: ["prettier-plugin-tailwindcss"],
tailwindFunctions: ["cn", "cva"],
overrides: [
{
files: "*.json.hbs",
options: {
parser: "json",
},
},
{
files: "*.js.hbs",
options: {
parser: "babel",
},
},
],
};
export default config;

View File

@@ -0,0 +1,23 @@
{
"name": "@turbostarter/prettier-config",
"version": "0.1.0",
"private": true,
"type": "module",
"exports": {
".": "./index.js"
},
"scripts": {
"clean": "git clean -xdf .cache .turbo node_modules",
"format": "prettier --check . --ignore-path ../../.gitignore",
"typecheck": "tsc --noEmit"
},
"prettier": "@turbostarter/prettier-config",
"dependencies": {
"prettier": "catalog:",
"prettier-plugin-tailwindcss": "^0.7.1"
},
"devDependencies": {
"@turbostarter/tsconfig": "workspace:*",
"typescript": "catalog:"
}
}

View File

@@ -0,0 +1,5 @@
{
"extends": "@turbostarter/tsconfig/base.json",
"include": ["."],
"exclude": ["node_modules"]
}

View File

@@ -0,0 +1,10 @@
{
"name": "scripts",
"private": true,
"version": "0.1.0",
"scripts": {
"dev": "node ./src/dev.mjs",
"requirements": "node ./src/requirements.mjs",
"license": "node ./src/license.mjs"
}
}

View File

@@ -0,0 +1,3 @@
import "./version.mjs";
import "./license.mjs";
import "./requirements.mjs";

View File

@@ -0,0 +1,86 @@
import { execSync } from "child_process";
function validateVisibility() {
let remoteUrl;
try {
remoteUrl = execSync("git config --get remote.origin.url")
.toString()
.trim();
} catch (error) {
return Promise.resolve();
}
if (!remoteUrl.includes("github.com")) {
return Promise.resolve();
}
let ownerRepo;
if (remoteUrl.startsWith("https://github.com/")) {
ownerRepo = remoteUrl.slice("https://github.com/".length);
} else if (remoteUrl.startsWith("git@github.com:")) {
ownerRepo = remoteUrl.slice("git@github.com:".length);
} else {
return;
}
ownerRepo = ownerRepo.replace(/\.git$/, "");
return fetch(`https://api.github.com/repos/${ownerRepo}`)
.then((res) => {
if (res.status === 200) {
return res.json();
} else if (res.status === 404) {
return Promise.resolve();
} else {
return Promise.reject(
new Error(
`GitHub API request failed with status code: ${res.status}`,
),
);
}
})
.then((data) => {
if (data && !data.private) {
console.error(
"The repository has been LEAKED on GitHub. Please delete the repository. A Takedown Request will automatically be requested in the coming hours.",
);
process.exit(1);
}
});
}
async function isOnline() {
const { lookup } = await import("dns");
try {
return await new Promise((resolve, reject) => {
lookup("google.com", (err) => {
if (err && err.code === "ENOTFOUND") {
reject(false);
} else {
resolve(true);
}
});
}).catch(() => false);
} catch (e) {
return false;
}
}
async function main() {
const isUserOnline = await isOnline();
if (!isUserOnline) {
return process.exit(0);
}
await validateVisibility();
}
void main().catch((error) => {
console.error(error);
process.exit(1);
});

View File

@@ -0,0 +1,58 @@
import { execSync } from "node:child_process";
export function checkPendingMigrations() {
try {
console.info("\x1b[34m%s\x1b[0m", "Checking for pending migrations...");
const output = execSync("pnpm --filter @turbostarter/db db:status", {
encoding: "utf-8",
stdio: "pipe",
});
const lines = output.split("\n");
const pendingStart = lines.findIndex(
(line) => line.trim() === "Pending migrations:",
);
let pendingMigrations = [];
if (pendingStart !== -1) {
for (let i = pendingStart + 1; i < lines.length; i++) {
const line = lines[i].trim();
if (line === "") continue;
if (line === "(none)") break;
if (line.startsWith("- ")) {
pendingMigrations.push(line.slice(2).trim());
} else {
break;
}
}
} else {
console.log(
"\x1b[33m%s\x1b[0m",
"⚠️ Could not determine pending migrations. Please check manually.",
);
return;
}
if (pendingMigrations.length > 0) {
console.log(
"\x1b[33m%s\x1b[0m",
"⚠️ There are pending migrations that need to be applied:",
);
pendingMigrations.forEach((migration) => console.log(` - ${migration}`));
console.log(
"\nSome functionality may not work as expected until these migrations are applied.",
);
console.log(
'\nAfter testing the migrations in your local environment and ideally in a staging environment, please run "pnpm --filter @turbostarter/db db:migrate" to apply them to your database. If you have any questions, please open a support ticket.',
);
} else {
console.log("\x1b[32m%s\x1b[0m", "✅ All migrations are up to date.");
}
} catch (error) {
console.log(
"\x1b[33m%s\x1b[0m",
"❌ Could not connect to the database. Please ensure your connection string is up to date and your database instance is running.\n",
);
}
}

View File

@@ -0,0 +1,61 @@
import { execSync } from "child_process";
// check requirements to run TurboStarter
void checkRequirements();
function checkRequirements() {
validateNodeInstalled();
validatePnpmInstalled();
validatePathNotOneDrive();
}
/**
* Validates that pnpm is installed.
* If pnpm is not installed, it exits the script with an error message.
*/
function validatePnpmInstalled() {
const currentPnpmVersion = execSync("pnpm --version").toString().trim();
if (!currentPnpmVersion) {
console.error(
`\x1b[31m%s\x1b[0m`,
`You are running TurboStarter from a directory that does not have pnpm installed. Please install pnpm and run "pnpm install" in your project directory.`,
);
process.exit(1);
}
}
/**
* Validates that Node is installed.
* If Node is not installed, it exits the script with an error message.
*/
function validateNodeInstalled() {
const currentNodeVersion = process.versions.node;
if (!currentNodeVersion) {
console.error(
`\x1b[31m%s\x1b[0m`,
`You are running TurboStarter from a device that does not have Node installed. Please install Node (https://nodejs.org/en/download/) and try again.`,
);
process.exit(1);
}
}
/**
* Checks if the current working directory is not OneDrive.
* If the current working directory is OneDrive, it exits the script with an error message.
*/
function validatePathNotOneDrive() {
const path = process.cwd();
if (path.includes("OneDrive")) {
console.error(
`\x1b[31m%s\x1b[0m`,
`You are running TurboStarter from OneDrive. Please move your project to a local folder.`,
);
process.exit(1);
}
}

View File

@@ -0,0 +1,93 @@
import { execSync } from "node:child_process";
import { checkPendingMigrations } from "./migrations.mjs";
function runGitCommand(command) {
try {
return execSync(command, { encoding: "utf8", stdio: "pipe" }).trim();
} catch (error) {
return null;
}
}
function checkTurboStarterVersion() {
const fetchResult = runGitCommand("git fetch upstream");
if (fetchResult === null) {
console.info(
"\x1b[33m%s\x1b[0m",
"⚠️ You have not setup 'upstream'. Please set up the upstream remote so you can update your TurboStarter version.",
);
return;
}
const behindCount = runGitCommand("git rev-list --count HEAD..upstream/main");
if (behindCount === null) {
console.warn(
"Failed to get commit count. Ensure you're on a branch that tracks upstream/main.",
);
return;
}
const count = parseInt(behindCount, 10);
const { severity } = getSeveriyLevel(count);
if (severity === "critical") {
console.log(
"\x1b[31m%s\x1b[0m",
"❌ Your TurboStarter version is outdated. Please update to the latest version.",
);
} else if (severity === "warning") {
console.log(
"\x1b[33m%s\x1b[0m",
"⚠️ Your TurboStarter version is outdated! Best to update to the latest version.",
);
} else {
console.log(
"\x1b[32m%s\x1b[0m",
"✅ Your TurboStarter version is up to date!",
);
}
if (count > 0) {
logInstructions(count);
}
}
function logInstructions(count) {
console.log(
"\x1b[33m%s\x1b[0m",
`You are ${count} commit(s) behind the latest version.`,
);
console.log(
"\x1b[33m%s\x1b[0m",
"Please consider updating to the latest version for bug fixes and optimizations that your version does not have.",
);
console.log("\x1b[36m%s\x1b[0m", "To update, run: git pull upstream main");
}
function getSeveriyLevel(count) {
if (count > 5) {
return {
severity: "critical",
};
}
if (count > 0) {
return {
severity: "warning",
};
}
return {
severity: "success",
};
}
checkTurboStarterVersion();
checkPendingMigrations();

View File

@@ -0,0 +1,27 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
"compilerOptions": {
"esModuleInterop": true,
"skipLibCheck": true,
"target": "ES2022",
"lib": ["ES2022"],
"allowJs": true,
"resolveJsonModule": true,
"moduleDetection": "force",
"isolatedModules": true,
"incremental": true,
"disableSourceOfProjectReferenceRedirect": true,
"tsBuildInfoFile": "${configDir}/.cache/tsbuildinfo.json",
"strict": true,
"noUncheckedIndexedAccess": true,
"checkJs": true,
"module": "Preserve",
"moduleResolution": "Bundler",
"noEmit": true,
},
"files": ["./reset.d.ts"],
"exclude": ["node_modules", "build", "dist", ".next", ".expo", ".wxt"]
}

View File

@@ -0,0 +1,10 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
"extends": "./base.json",
"compilerOptions": {
"declaration": true,
"declarationMap": true,
"noEmit": false,
"outDir": "${configDir}/dist"
}
}

View File

@@ -0,0 +1,11 @@
{
"name": "@turbostarter/tsconfig",
"version": "0.1.0",
"private": true,
"files": [
"*.json"
],
"devDependencies": {
"@total-typescript/ts-reset": "0.6.1"
}
}

2
tooling/typescript/reset.d.ts vendored Normal file
View File

@@ -0,0 +1,2 @@
// Do not add any other lines of code to this file!
import "@total-typescript/ts-reset";

View File

@@ -0,0 +1,28 @@
{
"name": "@turbostarter/vitest-config",
"version": "0.1.0",
"private": true,
"type": "module",
"exports": {
"./base": "./src/base.js"
},
"scripts": {
"clean": "git clean -xdf .cache .turbo coverage node_modules",
"test:coverage": "nyc report -t coverage/merged --report-dir coverage/report --reporter=html --exclude-after-remap false",
"test:coverage:collect": "pnpm dlx tsx ./src/scripts/collect-json-outputs.ts",
"test:coverage:merge": "nyc merge coverage/raw coverage/merged/merged-coverage.json",
"test:coverage:view": "open coverage/report/index.html"
},
"dependencies": {
"vitest": "catalog:"
},
"devDependencies": {
"@turbostarter/tsconfig": "workspace:*",
"@vitest/coverage-v8": "catalog:",
"@vitest/ui": "4.0.14",
"glob": "11.0.1",
"jsdom": "26.0.0",
"nyc": "17.1.0",
"typescript": "catalog:"
}
}

View File

@@ -0,0 +1,19 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
globals: true,
coverage: {
enabled: true,
provider: "v8",
reporter: [
[
"json",
{
file: `../coverage.json`,
},
],
],
},
},
});

View File

@@ -0,0 +1,73 @@
import fs from "fs/promises";
import path from "path";
import { glob } from "glob";
async function collectCoverageFiles() {
try {
// Define the patterns to search
const patterns = ["../../apps/*", "../../packages/*"];
// Define the destination directory (you can change this as needed)
const destinationDir = path.join(process.cwd(), "coverage/raw");
// Create the destination directory if it doesn't exist
await fs.mkdir(destinationDir, { recursive: true });
// Arrays to collect all directories and directories with coverage.json
const allDirectories = [];
const directoriesWithCoverage = [];
// Process each pattern
for (const pattern of patterns) {
// Find all paths matching the pattern
const matches = await glob(pattern);
// Filter to only include directories
for (const match of matches) {
const stats = await fs.stat(match);
if (stats.isDirectory()) {
allDirectories.push(match);
const coverageFilePath = path.join(match, "coverage.json");
// Check if coverage.json exists in this directory
try {
await fs.access(coverageFilePath);
// File exists, add to list of directories with coverage
directoriesWithCoverage.push(match);
// Copy it to the destination with a unique name
const directoryName = path.basename(match);
const destinationFile = path.join(
destinationDir,
`${directoryName}.json`
);
await fs.copyFile(coverageFilePath, destinationFile);
} catch (err) {
// File doesn't exist in this directory, skip
}
}
}
}
// Create clean patterns for display (without any "../" prefixes)
const replaceDotPatterns = (str: string) => str.replace(/\.\.\//g, "");
if (directoriesWithCoverage.length > 0) {
console.log(
`Found coverage.json in: ${directoriesWithCoverage
.map(replaceDotPatterns)
.join(", ")}`
);
}
console.log(`Coverage collected into: ${path.join(process.cwd())}`);
} catch (error) {
console.error("Error collecting coverage files:", error);
}
}
// Run the function
collectCoverageFiles();

View File

@@ -0,0 +1,6 @@
{
"extends": "@turbostarter/tsconfig/internal.json",
"compilerOptions": {},
"include": ["*.ts", "src/**/*"],
"exclude": ["node_modules"]
}

22
tooling/vitest/turbo.json Normal file
View File

@@ -0,0 +1,22 @@
{
"extends": ["//"],
"tasks": {
"test:coverage:collect": {
"cache": false
},
"test:coverage:merge": {
"dependsOn": ["test:coverage:collect"],
"inputs": ["coverage/raw/**"],
"outputs": ["coverage/merged/**"]
},
"test:coverage": {
"dependsOn": ["test:coverage:merge"],
"inputs": ["coverage/merge"],
"outputs": ["coverage/report/**"]
},
"test:coverage:view": {
"dependsOn": ["test:coverage"],
"cache": false
}
}
}