create-shiftapi 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+<p align="center">
+	<img src="https://raw.githubusercontent.com/fcjr/shiftapi/main/assets/logo.svg" alt="ShiftAPI Logo">
+</p>
+
+# create-shiftapi
+
+Scaffold a new [ShiftAPI](https://github.com/fcjr/shiftapi) fullstack app — Go server + typed TypeScript frontend.
+
+## Usage
+
+```bash
+npm create shiftapi
+```
+
+Or with pnpm / yarn:
+
+```bash
+pnpm create shiftapi
+yarn create shiftapi
+```
+
+You can also pass the project name directly:
+
+```bash
+npm create shiftapi my-app
+```
+
+## What You Get
+
+```
+my-app/
+  cmd/my-app/main.go              # Go entry point with graceful shutdown
+  internal/server/server.go        # API routes and handlers
+  go.mod
+  .env                             # PORT config
+  .gitignore
+  package.json                     # Monorepo root with workspaces
+  apps/web/
+    package.json                   # React or Svelte frontend
+    vite.config.ts                 # ShiftAPI vite plugin configured
+    tsconfig.json
+    index.html
+    src/
+      main.tsx (or .ts)            # App entry
+      App.tsx (or .svelte)         # Demo component with typed API calls
+```
+
+## Prompts
+
+| Prompt | Default |
+|---|---|
+| Project name | `my-app` |
+| Framework | React / Svelte |
+| Directory | `./<project-name>` |
+| Go module path | `github.com/<gh-user>/<project-name>` if logged into `gh`, otherwise `<project-name>` |
+| Server port | `8080` |
+
+## After Scaffolding
+
+```bash
+cd my-app
+go mod tidy
+npm install
+npm run dev
+```
+
+This starts the Go server and Vite dev server together. The frontend gets fully typed API clients generated from your Go handlers — edit a struct in Go, get instant type errors in TypeScript.
+
+API docs are served at `http://localhost:8080/docs`.

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs2 from "fs";
+import os from "os";
+import * as p from "@clack/prompts";
+import path2 from "path";
+
+// src/scaffold.ts
+import { execFile } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var renameFiles = {
+  _gitignore: ".gitignore"
+};
+var pkgDir = path.resolve(fileURLToPath(import.meta.url), "../..");
+var templatesDir = path.join(pkgDir, "templates");
+var pkgVersion = JSON.parse(
+  fs.readFileSync(path.join(pkgDir, "package.json"), "utf-8")
+).version;
+function replaceplaceholders(content, opts) {
+  return content.replaceAll("{{name}}", opts.name).replaceAll("{{modulePath}}", opts.modulePath).replaceAll("{{port}}", opts.port).replaceAll("{{version}}", pkgVersion);
+}
+function renamePath(filePath, opts) {
+  return filePath.replaceAll("__name__", opts.name);
+}
+function copyDir(srcDir, destDir, opts) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir)) {
+    const srcPath = path.join(srcDir, entry);
+    const destName = renameFiles[entry] ?? entry;
+    const destPath = path.join(destDir, renamePath(destName, opts));
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+      copyDir(srcPath, destPath, opts);
+    } else {
+      const content = fs.readFileSync(srcPath, "utf-8");
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.writeFileSync(destPath, replaceplaceholders(content, opts));
+    }
+  }
+}
+function gitInit(cwd) {
+  return new Promise((resolve, reject) => {
+    execFile("git", ["init"], { cwd }, (err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+async function scaffold(opts) {
+  copyDir(path.join(templatesDir, "base"), opts.targetDir, opts);
+  copyDir(path.join(templatesDir, opts.framework), opts.targetDir, opts);
+  await gitInit(opts.targetDir);
+}
+
+// src/index.ts
+function expandHome(filepath) {
+  if (filepath === "~" || filepath.startsWith("~/")) {
+    return path2.join(os.homedir(), filepath.slice(1));
+  }
+  return filepath;
+}
+function getGitHubUser() {
+  const configDir = expandHome(
+    process.env.GH_CONFIG_DIR ?? process.env.XDG_CONFIG_HOME ? path2.join(expandHome(process.env.XDG_CONFIG_HOME), "gh") : path2.join(os.homedir(), ".config", "gh")
+  );
+  try {
+    const hosts = fs2.readFileSync(path2.join(configDir, "hosts.yml"), "utf-8");
+    const match = hosts.match(/github\.com:\s[\s\S]*?^\s+user:\s+(.+)$/m);
+    return match?.[1]?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const positionalName = process.argv[2];
+  const ghUser = getGitHubUser();
+  p.intro("create-shiftapi");
+  const project = await p.group(
+    {
+      name: () => positionalName ? Promise.resolve(positionalName) : p.text({
+        message: "Project name",
+        placeholder: "my-app",
+        defaultValue: "my-app"
+      }),
+      framework: () => p.select({
+        message: "Framework",
+        options: [
+          { label: "React", value: "react" },
+          { label: "Svelte", value: "svelte" }
+        ]
+      }),
+      directory: ({ results }) => p.text({
+        message: "Directory",
+        placeholder: `./${results.name}`,
+        defaultValue: `./${results.name}`
+      }),
+      module: ({ results }) => p.text({
+        message: "Go module path",
+        placeholder: ghUser ? `github.com/${ghUser}/${results.name}` : results.name,
+        defaultValue: ghUser ? `github.com/${ghUser}/${results.name}` : results.name
+      }),
+      port: () => p.text({
+        message: "Server port",
+        placeholder: "8080",
+        defaultValue: "8080"
+      })
+    },
+    {
+      onCancel: () => {
+        p.cancel("Cancelled.");
+        process.exit(1);
+      }
+    }
+  );
+  const targetDir = path2.resolve(process.cwd(), expandHome(project.directory));
+  if (fs2.existsSync(targetDir)) {
+    p.cancel(`${targetDir} already exists.`);
+    process.exit(1);
+  }
+  const s = p.spinner();
+  s.start("Scaffolding project");
+  await scaffold({
+    name: project.name,
+    modulePath: project.module,
+    port: project.port,
+    framework: project.framework,
+    targetDir
+  });
+  s.stop("Project scaffolded");
+  const relDir = path2.relative(process.cwd(), targetDir) || ".";
+  p.note(
+    [`cd ${relDir}`, "go mod tidy", "npm install", "npm run dev"].join("\n"),
+    "Next steps"
+  );
+  p.outro("Happy hacking!");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-shiftapi",
+  "version": "0.0.1",
+  "description": "Scaffold a new ShiftAPI fullstack app",
+  "type": "module",
+  "bin": {
+    "create-shiftapi": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/templates/base/.env

@@ -0,0 +1 @@
+PORT={{port}}

package/templates/base/README.md

@@ -0,0 +1,32 @@
+# {{name}}
+
+Built with [ShiftAPI](https://github.com/fcjr/shiftapi) — Go server + typed TypeScript frontend.
+
+## Getting Started
+
+```bash
+go mod tidy
+npm install
+npm run dev
+```
+
+This starts the Go server and Vite dev server together. The frontend gets fully typed API clients generated from your Go handlers.
+
+- API docs: http://localhost:{{port}}/docs
+- Frontend: http://localhost:5173
+
+## Project Structure
+
+```
+cmd/{{name}}/main.go          # Go entry point
+internal/server/server.go      # API routes and handlers
+go.mod
+.env                           # Environment variables (PORT)
+apps/web/                      # Frontend (Vite + TypeScript)
+```
+
+## Scripts
+
+```bash
+npm run dev       # Start Go server + Vite dev server
+```

package/templates/base/_gitignore

@@ -0,0 +1,22 @@
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Node
+node_modules/
+dist/
+.turbo/
+
+# Env
+.env
+
+# IDE
+.DS_Store
+*.log
+.vscode/
+.idea/

package/templates/base/cmd/__name__/main.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"os/signal"
+
+	"github.com/joho/godotenv"
+
+	"{{modulePath}}/internal/server"
+)
+
+func main() {
+	ctx := context.Background()
+
+	if err := godotenv.Load(); err != nil {
+		slog.Warn("error loading .env file, skipping", "error", err)
+	}
+
+	if err := run(ctx, os.Args, os.Getenv, os.Stdin, os.Stdout, os.Stderr); err != nil {
+		fmt.Fprintf(os.Stderr, "%v\n", err)
+		os.Exit(1)
+	}
+}
+
+func run(ctx context.Context, args []string, getenv func(string) string, stdin io.Reader, stdout, stderr io.Writer) error {
+	ctx, cancel := signal.NotifyContext(ctx, os.Interrupt)
+	defer cancel()
+
+	port := getenv("PORT")
+	if port == "" {
+		port = "{{port}}"
+	}
+
+	slog.Info("starting server", "port", port)
+	// docs at http://localhost:{{port}}/docs
+	return server.ListenAndServe(ctx, ":"+port)
+}

package/templates/base/go.mod

@@ -0,0 +1,5 @@
+module {{modulePath}}
+
+go 1.24.0
+
+require github.com/fcjr/shiftapi v{{version}}

package/templates/base/internal/server/server.go

@@ -0,0 +1,51 @@
+package server
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/fcjr/shiftapi"
+)
+
+type EchoRequest struct {
+	Message string `json:"message" validate:"required"`
+}
+
+type EchoResponse struct {
+	Message string `json:"message"`
+}
+
+func echo(r *http.Request, body *EchoRequest) (*EchoResponse, error) {
+	return &EchoResponse{Message: body.Message}, nil
+}
+
+type Status struct {
+	OK bool `json:"ok"`
+}
+
+func health(r *http.Request) (*Status, error) {
+	return &Status{OK: true}, nil
+}
+
+func ListenAndServe(ctx context.Context, addr string) error {
+	api := shiftapi.New(shiftapi.WithInfo(shiftapi.Info{
+		Title: "{{name}}",
+	}))
+
+	shiftapi.Post(api, "/echo", echo,
+		shiftapi.WithRouteInfo(shiftapi.RouteInfo{
+			Summary:     "Echo a message",
+			Description: "Returns the message you send",
+			Tags:        []string{"echo"},
+		}),
+	)
+
+	shiftapi.Get(api, "/health", health,
+		shiftapi.WithRouteInfo(shiftapi.RouteInfo{
+			Summary: "Health check",
+			Tags:    []string{"health"},
+		}),
+	)
+
+	return shiftapi.ListenAndServe(addr, api)
+}

package/templates/base/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "scripts": {
+    "dev": "npm run dev --workspace apps/web"
+  },
+  "workspaces": [
+    "apps/*"
+  ]
+}

package/templates/react/apps/web/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react/apps/web/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@{{name}}/web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@shiftapi/vite-plugin": "^{{version}}",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0"
+  }
+}

package/templates/react/apps/web/src/App.tsx

@@ -0,0 +1,42 @@
+import { useEffect, useState } from "react";
+import type { FormEvent } from "react";
+import { client } from "@shiftapi/client";
+
+export default function App() {
+  const [output, setOutput] = useState("");
+
+  useEffect(() => {
+    client.GET("/health").then(({ error }) => {
+      if (error) {
+        setOutput(`Health check failed: ${error.message}`);
+      } else {
+        setOutput("Health check passed. Try sending a message.");
+      }
+    });
+  }, []);
+
+  async function handleSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const message = (formData.get("message") as string).trim();
+    if (!message) return;
+    setOutput("Loading...");
+    const { data, error } = await client.POST("/echo", { body: { message } });
+    if (error) {
+      setOutput(`Error: ${error.message}`);
+    } else {
+      setOutput(`Echo: ${data.message}`);
+    }
+  }
+
+  return (
+    <div>
+      <h1>{{name}}</h1>
+      <form onSubmit={handleSubmit}>
+        <input type="text" name="message" placeholder="Enter a message" />
+        <button type="submit">Send</button>
+      </form>
+      <pre>{output}</pre>
+    </div>
+  );
+}

package/templates/react/apps/web/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/react/apps/web/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "paths": {
+      "@shiftapi/client": [
+        "./node_modules/.shiftapi/client.d.ts"
+      ]
+    }
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/react/apps/web/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import shiftapi from "@shiftapi/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    shiftapi({
+      server: "./cmd/{{name}}",
+      goRoot: "../..",
+    }),
+  ],
+});

package/templates/svelte/apps/web/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/svelte/apps/web/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@{{name}}/web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@shiftapi/vite-plugin": "^{{version}}",
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0"
+  }
+}

package/templates/svelte/apps/web/src/App.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+  import { client } from "@shiftapi/client";
+
+  let output = $state("");
+
+  $effect(() => {
+    client.GET("/health").then(({ error }) => {
+      if (error) {
+        output = `Health check failed: ${error.message}`;
+      } else {
+        output = "Health check passed. Try sending a message.";
+      }
+    });
+  });
+
+  async function handleSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget as HTMLFormElement);
+    const message = (formData.get("message") as string).trim();
+    if (!message) return;
+    output = "Loading...";
+    const { data, error } = await client.POST("/echo", { body: { message } });
+    if (error) {
+      output = `Error: ${error.message}`;
+    } else {
+      output = `Echo: ${data.message}`;
+    }
+  }
+</script>
+
+<div>
+  <h1>{{name}}</h1>
+  <form onsubmit={handleSubmit}>
+    <input type="text" name="message" placeholder="Enter a message" />
+    <button type="submit">Send</button>
+  </form>
+  <pre>{output}</pre>
+</div>

package/templates/svelte/apps/web/src/main.ts

@@ -0,0 +1,4 @@
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+mount(App, { target: document.getElementById("app")! });

package/templates/svelte/apps/web/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@shiftapi/client": [
+        "./node_modules/.shiftapi/client.d.ts"
+      ]
+    }
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/svelte/apps/web/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import shiftapi from "@shiftapi/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    svelte(),
+    shiftapi({
+      server: "./cmd/{{name}}",
+      goRoot: "../..",
+    }),
+  ],
+});