create-nscope-app 1.0.0

package/bin/create-nscope-app.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import { cp, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stdin as input, stdout as output } from "node:process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, "..", "templates");
+
+const TEMPLATE_CHOICES = ["vite", "next"];
+
+function parseArgs(argv) {
+  const result = {
+    projectName: "",
+    template: "",
+    apiKey: "",
+    baseUrl: "http://localhost:3333",
+    redirectUri: "http://localhost:5173",
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+      continue;
+    }
+
+    if (arg === "--template" || arg === "-t") {
+      result.template = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--api-key") {
+      result.apiKey = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--base-url") {
+      result.baseUrl = argv[index + 1] ?? result.baseUrl;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--redirect-uri") {
+      result.redirectUri = argv[index + 1] ?? result.redirectUri;
+      index += 1;
+      continue;
+    }
+
+    if (!arg.startsWith("-") && !result.projectName) {
+      result.projectName = arg;
+    }
+  }
+
+  return result;
+}
+
+function printHelp() {
+  console.log(`
+create-nscope-app — scaffold a Nscope client app
+
+Usage:
+  npx create-nscope-app <project-name> [options]
+
+Options:
+  -t, --template <vite|next>   Template (default: vite)
+      --api-key <key>            Nscope API key (pk_live_...)
+      --base-url <url>           API base URL (default: http://localhost:3333)
+      --redirect-uri <url>       OAuth return URL (default: http://localhost:5173)
+  -h, --help                     Show this help
+
+Examples:
+  npx create-nscope-app my-saas --template vite
+  npx create-nscope-app my-saas -t next --api-key pk_live_xxx
+`);
+}
+
+async function prompt(question, defaultValue = "") {
+  const rl = createInterface({ input, output });
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = (await rl.question(`${question}${suffix}: `)).trim();
+  rl.close();
+  return answer || defaultValue;
+}
+
+async function copyDir(source, destination, replacements) {
+  await mkdir(destination, { recursive: true });
+  const entries = await readdir(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = join(source, entry.name);
+    const destPath = join(destination, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(sourcePath, destPath, replacements);
+      continue;
+    }
+
+    let content = await readFile(sourcePath, "utf8");
+
+    for (const [key, value] of Object.entries(replacements)) {
+      content = content.replaceAll(`{{${key}}}`, value);
+    }
+
+    await writeFile(destPath, content, "utf8");
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const projectName =
+    args.projectName || (await prompt("Project name", "my-nscope-app"));
+  const template =
+    args.template ||
+    (await prompt(`Template (${TEMPLATE_CHOICES.join("|")})`, "vite"));
+
+  if (!TEMPLATE_CHOICES.includes(template)) {
+    console.error(`Invalid template "${template}". Use: ${TEMPLATE_CHOICES.join(", ")}`);
+    process.exit(1);
+  }
+
+  const apiKey =
+    args.apiKey || (await prompt("API key (pk_live_...)", "pk_live_YOUR_KEY"));
+  const baseUrl =
+    args.baseUrl || (await prompt("API base URL", "http://localhost:3333"));
+  const redirectUri =
+    args.redirectUri ||
+    (await prompt(
+      "Redirect URI",
+      template === "next" ? "http://localhost:3000" : "http://localhost:5173",
+    ));
+
+  const targetDir = resolve(process.cwd(), projectName);
+  const templateDir = join(TEMPLATES_DIR, template);
+
+  try {
+    await stat(templateDir);
+  } catch {
+    console.error(`Template not found: ${template}`);
+    process.exit(1);
+  }
+
+  try {
+    await stat(targetDir);
+    console.error(`Directory already exists: ${targetDir}`);
+    process.exit(1);
+  } catch {
+    // ok
+  }
+
+  const replacements = {
+    PROJECT_NAME: projectName,
+    API_KEY: apiKey,
+    BASE_URL: baseUrl,
+    REDIRECT_URI: redirectUri,
+  };
+
+  await copyDir(templateDir, targetDir, replacements);
+
+  console.log(`
+✓ Created ${projectName} (${template})
+
+Next steps:
+  cd ${projectName}
+  pnpm install
+  pnpm dev
+
+Docs: https://github.com/tratondigital/nscope-app — /docs/sdk
+`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "create-nscope-app",
+  "version": "1.0.0",
+  "description": "Scaffold a Nscope client app (Vite or Next.js)",
+  "type": "module",
+  "bin": {
+    "create-nscope-app": "./bin/create-nscope-app.mjs"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "keywords": [
+    "nscope",
+    "auth",
+    "scaffold",
+    "vite",
+    "next"
+  ],
+  "license": "ISC",
+  "author": "Traton Digital"
+}

package/templates/next/.env.local.example

@@ -0,0 +1,3 @@
+NEXT_PUBLIC_NSCOPE_API_KEY={{API_KEY}}
+NEXT_PUBLIC_NSCOPE_BASE_URL={{BASE_URL}}
+NEXT_PUBLIC_NSCOPE_REDIRECT_URI={{REDIRECT_URI}}

package/templates/next/README.md

@@ -0,0 +1,21 @@
+# {{PROJECT_NAME}}
+
+Starter Next.js App Router with [@nscope/react](https://www.npmjs.com/package/@nscope/react).
+
+## Setup
+
+1. Copy `.env.local.example` to `.env.local` and fill in your API key.
+2. Add `{{REDIRECT_URI}}` to **allowed domains** and as default return URL in Nscope.
+3. Run:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Next steps
+
+- Wrap protected pages with `<GuardedRoute>`
+- See `/docs/sdk` in your Nscope dashboard

package/templates/next/app/globals.css

@@ -0,0 +1,30 @@
+:root {
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.5;
+  color: #18181b;
+  background: #fafafa;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+.page {
+  max-width: 640px;
+  margin: 4rem auto;
+  padding: 0 1rem;
+}
+
+button {
+  border: none;
+  border-radius: 8px;
+  background: #18181b;
+  color: white;
+  padding: 0.65rem 1rem;
+  font: inherit;
+  cursor: pointer;
+}

package/templates/next/app/layout.tsx

@@ -0,0 +1,22 @@
+import type { Metadata } from "next";
+import { Providers } from "@/components/providers";
+import { HomePage } from "@/components/home-page";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "{{PROJECT_NAME}}",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/next/app/page.tsx

@@ -0,0 +1,5 @@
+import { HomePage } from "@/components/home-page";
+
+export default function Page() {
+  return <HomePage />;
+}

package/templates/next/components/home-page.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { Can, useNscope } from "@nscope/react";
+
+export function HomePage() {
+  const { user, isAuthenticated, isLoading, login, logout } = useNscope();
+
+  if (isLoading) {
+    return <main className="page">Loading…</main>;
+  }
+
+  return (
+    <main className="page">
+      <h1>{{PROJECT_NAME}}</h1>
+
+      {isAuthenticated && user ? (
+        <>
+          <p>Signed in as {user.name ?? user.email}</p>
+          <Can subject="users" action="LIST">
+            <p>You can list users.</p>
+          </Can>
+          <button type="button" onClick={() => logout()}>
+            Sign out
+          </button>
+        </>
+      ) : (
+        <button
+          type="button"
+          onClick={() =>
+            login({
+              redirectUri: process.env.NEXT_PUBLIC_NSCOPE_REDIRECT_URI,
+            })
+          }
+        >
+          Sign in with Nscope
+        </button>
+      )}
+    </main>
+  );
+}

package/templates/next/components/providers.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { NscopeProvider } from "@nscope/react";
+import { nscope } from "@/lib/nscope";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <NscopeProvider config={nscope}>{children}</NscopeProvider>;
+}

package/templates/next/lib/nscope.ts

@@ -0,0 +1,10 @@
+import { SDK } from "@nscope/sdk";
+
+export const nscope = SDK.init({
+  baseUrl: process.env.NEXT_PUBLIC_NSCOPE_BASE_URL!,
+  apiKey: process.env.NEXT_PUBLIC_NSCOPE_API_KEY!,
+  auth: {
+    autoHandleCallback: true,
+    storage: "localStorage",
+  },
+});

package/templates/next/next-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />

package/templates/next/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;

package/templates/next/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@nscope/react": "^1.0.0",
+    "@nscope/sdk": "^1.3.0",
+    "next": "^15.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/next/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/vite/.env.example

@@ -0,0 +1,3 @@
+VITE_NSCOPE_API_KEY={{API_KEY}}
+VITE_NSCOPE_BASE_URL={{BASE_URL}}
+VITE_NSCOPE_REDIRECT_URI={{REDIRECT_URI}}

package/templates/vite/README.md

@@ -0,0 +1,20 @@
+# {{PROJECT_NAME}}
+
+Starter Vite + React with [@nscope/react](https://www.npmjs.com/package/@nscope/react).
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your API key from the Nscope dashboard.
+2. Add `{{REDIRECT_URI}}` to **allowed domains** and set it as the default return URL in project settings.
+3. Run:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Next steps
+
+- Customize login redirect in `src/App.tsx`
+- Protect routes with `<GuardedRoute>` from `@nscope/react`
+- Read the SDK docs in your Nscope panel at `/docs/sdk`

package/templates/vite/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>{{PROJECT_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/vite/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@nscope/react": "^1.0.0",
+    "@nscope/sdk": "^1.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.4.0",
+    "typescript": "^5.9.0",
+    "vite": "^6.3.0"
+  }
+}

package/templates/vite/src/App.tsx

@@ -0,0 +1,31 @@
+import { Can, useNscope } from "@nscope/react";
+
+export default function App() {
+  const { user, isAuthenticated, isLoading, login, logout } = useNscope();
+
+  if (isLoading) {
+    return <main className="page">Loading…</main>;
+  }
+
+  return (
+    <main className="page">
+      <h1>{{PROJECT_NAME}}</h1>
+
+      {isAuthenticated && user ? (
+        <>
+          <p>Signed in as {user.name ?? user.email}</p>
+          <Can subject="users" action="LIST">
+            <p>You can list users.</p>
+          </Can>
+          <button type="button" onClick={() => logout()}>
+            Sign out
+          </button>
+        </>
+      ) : (
+        <button type="button" onClick={() => login({ redirectUri: import.meta.env.VITE_NSCOPE_REDIRECT_URI })}>
+          Sign in with Nscope
+        </button>
+      )}
+    </main>
+  );
+}

package/templates/vite/src/index.css

@@ -0,0 +1,30 @@
+:root {
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.5;
+  color: #18181b;
+  background: #fafafa;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+.page {
+  max-width: 640px;
+  margin: 4rem auto;
+  padding: 0 1rem;
+}
+
+button {
+  border: none;
+  border-radius: 8px;
+  background: #18181b;
+  color: white;
+  padding: 0.65rem 1rem;
+  font: inherit;
+  cursor: pointer;
+}

package/templates/vite/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { NscopeProvider } from "@nscope/react";
+import App from "./App";
+import { nscope } from "./nscope";
+import "./index.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <NscopeProvider config={nscope}>
+      <App />
+    </NscopeProvider>
+  </StrictMode>,
+);

package/templates/vite/src/nscope.ts

@@ -0,0 +1,10 @@
+import { SDK } from "@nscope/sdk";
+
+export const nscope = SDK.init({
+  baseUrl: import.meta.env.VITE_NSCOPE_BASE_URL,
+  apiKey: import.meta.env.VITE_NSCOPE_API_KEY,
+  auth: {
+    autoHandleCallback: true,
+    storage: "localStorage",
+  },
+});

package/templates/vite/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/templates/vite/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+});