[CRA] Configure create-instant-app for self-hosted backends

client/packages/create-instant-app/scripts/copyExamples.ts

@@ -2,17 +2,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import fs from 'fs-extra';
 import { copyRespectingGitignore } from '../src/scaffold.js';
-
-const EXAMPLES_TO_COPY = [
-  'expo',
-  'next-js-app-dir',
-  'sveltekit',
-  'vite-react',
-  'vite-vanilla',
-  'tanstack-start',
-  'vue-vite',
-  'python-script',
-] as const;
+import { bundledProjectBases } from '../src/projectBase.js';
 
 async function main() {
   const __filename = fileURLToPath(import.meta.url);
@@ -23,7 +13,7 @@ async function main() {
   const templateBaseRoot = path.join(__dirname, '../template/base');
 
   const copiedExamples = await Promise.all(
-    EXAMPLES_TO_COPY.map(async (exampleName) => {
+    bundledProjectBases.map(async (exampleName) => {
       const sourceDir = path.join(examplesRoot, exampleName);
       const targetDir = path.join(templateBaseRoot, exampleName);
 

client/packages/create-instant-app/src/backendConfig.test.ts

@@ -0,0 +1,127 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { afterEach, describe, expect, it } from 'vitest';
+import { applyBackendConfig, websocketURIFromAPIURI } from './backendConfig.js';
+import { projectBaseConfig, projectBases } from './projectBase.js';
+
+const tempDirs: string[] = [];
+const examplesDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../examples',
+);
+
+const createTempDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'backend-config-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.removeSync(dir);
+  }
+});
+
+describe('websocketURIFromAPIURI', () => {
+  it.each([
+    ['http://localhost:8888', 'ws://localhost:8888/runtime/session'],
+    ['https://instant.example', 'wss://instant.example/runtime/session'],
+    [
+      'https://instant.example/backend/',
+      'wss://instant.example/backend/runtime/session',
+    ],
+  ])('derives a websocket URI from %s', (apiURI, expected) => {
+    expect(websocketURIFromAPIURI(apiURI)).toBe(expected);
+  });
+
+  it('rejects non-HTTP URIs', () => {
+    expect(() => websocketURIFromAPIURI('ftp://instant.example')).toThrow(
+      'INSTANT_CLI_API_URI must be a valid HTTP(S) URL',
+    );
+  });
+
+  it('rejects malformed URIs', () => {
+    expect(() => websocketURIFromAPIURI('instant.example')).toThrow(
+      'INSTANT_CLI_API_URI must be a valid HTTP(S) URL',
+    );
+  });
+});
+
+describe('applyBackendConfig', () => {
+  it('adds API and websocket URIs to a client init', () => {
+    const dir = createTempDir();
+    const filePath = path.join(dir, 'src/lib/db.ts');
+    fs.outputFileSync(
+      filePath,
+      'export const db = init({\n  appId: "app-id",\n});\n',
+    );
+
+    applyBackendConfig('next-js-app-dir', dir, 'http://localhost:8888/');
+
+    expect(fs.readFileSync(filePath, 'utf8')).toBe(
+      'export const db = init({\n' +
+        '  apiURI: "http://localhost:8888",\n' +
+        '  websocketURI: "ws://localhost:8888/runtime/session",\n' +
+        '  appId: "app-id",\n' +
+        '});\n',
+    );
+  });
+
+  it('adds only the API URI to admin init', () => {
+    const dir = createTempDir();
+    const clientPath = path.join(dir, 'src/lib/db.ts');
+    const adminPath = path.join(dir, 'src/lib/adminDb.ts');
+    fs.outputFileSync(clientPath, 'export const db = init({\n});\n');
+    fs.outputFileSync(adminPath, 'export const adminDb = init({\n});\n');
+
+    applyBackendConfig('tanstack-start', dir, 'https://instant.example');
+
+    expect(fs.readFileSync(adminPath, 'utf8')).toContain(
+      'init({\n  apiURI: "https://instant.example",\n',
+    );
+    expect(fs.readFileSync(adminPath, 'utf8')).not.toContain('websocketURI');
+  });
+
+  it('does not update any files if a template cannot be configured', () => {
+    const dir = createTempDir();
+    const clientPath = path.join(dir, 'src/lib/db.ts');
+    const adminPath = path.join(dir, 'src/lib/adminDb.ts');
+    const clientContents = 'export const db = init({\n});\n';
+    fs.outputFileSync(clientPath, clientContents);
+    fs.outputFileSync(adminPath, 'export const adminDb = unknownInit({});\n');
+
+    expect(() =>
+      applyBackendConfig('tanstack-start', dir, 'https://instant.example'),
+    ).toThrow('Could not find init({ in scaffolded database file');
+    expect(fs.readFileSync(clientPath, 'utf8')).toBe(clientContents);
+  });
+
+  it('configures the Python client', () => {
+    const dir = createTempDir();
+    const filePath = path.join(dir, 'main.py');
+    fs.outputFileSync(filePath, 'db = Instant()\n');
+
+    applyBackendConfig('python-script', dir, 'https://instant.example/');
+
+    expect(fs.readFileSync(filePath, 'utf8')).toBe(
+      'db = Instant(api_uri="https://instant.example")\n',
+    );
+  });
+});
+
+describe('project base backend config', () => {
+  it.each(projectBases)('%s matches its example template', (base) => {
+    for (const file of projectBaseConfig[base].backendConfigFiles) {
+      const contents = fs.readFileSync(
+        path.join(examplesDir, base, file.path),
+        'utf8',
+      );
+      const initializer =
+        file.type === 'python' ? 'db = Instant()' : `${file.initializer}({`;
+
+      expect(contents).toContain(initializer);
+    }
+  });
+});

client/packages/create-instant-app/src/backendConfig.ts

@@ -0,0 +1,115 @@
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  projectBaseConfig,
+  type BackendConfigFile,
+  type ProjectBase,
+} from './projectBase.js';
+
+const normalizeAPIURI = (apiURI: string) => apiURI.replace(/\/+$/, '');
+
+export const websocketURIFromAPIURI = (apiURI: string) => {
+  let websocketURI: URL;
+  try {
+    websocketURI = new URL(normalizeAPIURI(apiURI));
+  } catch {
+    throw new Error('INSTANT_CLI_API_URI must be a valid HTTP(S) URL');
+  }
+
+  if (websocketURI.protocol === 'http:') {
+    websocketURI.protocol = 'ws:';
+  } else if (websocketURI.protocol === 'https:') {
+    websocketURI.protocol = 'wss:';
+  } else {
+    throw new Error('INSTANT_CLI_API_URI must be a valid HTTP(S) URL');
+  }
+
+  websocketURI.pathname = `${websocketURI.pathname.replace(/\/+$/, '')}/runtime/session`;
+  websocketURI.search = '';
+  websocketURI.hash = '';
+
+  return websocketURI.toString();
+};
+
+const injectInitConfig = ({
+  contents,
+  initializer,
+  apiURI,
+  websocketURI,
+}: {
+  contents: string;
+  initializer: string;
+  apiURI: string;
+  websocketURI?: string;
+}) => {
+  const initStart = `${initializer}({`;
+  if (!contents.includes(initStart)) {
+    throw new Error(`Could not find ${initStart} in scaffolded database file`);
+  }
+
+  const config = [
+    `  apiURI: ${JSON.stringify(apiURI)},`,
+    websocketURI ? `  websocketURI: ${JSON.stringify(websocketURI)},` : null,
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  return contents.replace(initStart, `${initStart}\n${config}`);
+};
+
+const injectPythonConfig = (contents: string, apiURI: string) => {
+  const initStart = 'db = Instant()';
+  if (!contents.includes(initStart)) {
+    throw new Error(`Could not find ${initStart} in scaffolded database file`);
+  }
+
+  return contents.replace(
+    initStart,
+    `db = Instant(api_uri=${JSON.stringify(apiURI)})`,
+  );
+};
+
+const injectBackendConfig = (
+  file: BackendConfigFile,
+  contents: string,
+  apiURI: string,
+  websocketURI: string,
+) => {
+  if (file.type === 'python') {
+    return injectPythonConfig(contents, apiURI);
+  }
+
+  return injectInitConfig({
+    contents,
+    initializer: file.initializer,
+    apiURI,
+    websocketURI: file.websocket ? websocketURI : undefined,
+  });
+};
+
+export const applyBackendConfig = (
+  base: ProjectBase,
+  projectDir: string,
+  apiURI: string,
+) => {
+  const normalizedAPIURI = normalizeAPIURI(apiURI);
+  const websocketURI = websocketURIFromAPIURI(normalizedAPIURI);
+
+  const updates = projectBaseConfig[base].backendConfigFiles.map((file) => {
+    const filePath = path.join(projectDir, file.path);
+    const contents = fs.readFileSync(filePath, 'utf8');
+    return {
+      filePath,
+      contents: injectBackendConfig(
+        file,
+        contents,
+        normalizedAPIURI,
+        websocketURI,
+      ),
+    };
+  });
+
+  for (const update of updates) {
+    fs.writeFileSync(update.filePath, update.contents);
+  }
+};

client/packages/create-instant-app/src/cli.ts

@@ -4,22 +4,10 @@ import { findClaudePath } from './claude.js';
 import { version } from '@instantdb/version';
 import { coerceAppName, validateAppName } from './utils/validateAppName.js';
 import { renderUnwrap, UI } from 'instant-cli/ui';
+import { projectBases, type ProjectBase } from './projectBase.js';
 
 export type Project = {
-  base:
-    | 'next-js-app-dir'
-    | 'vite-react'
-    | 'vite-vanilla'
-    | 'expo'
-    | 'tanstack-start'
-    | 'tanstack-start-with-tanstack-query'
-    | 'bun-react'
-    | 'solidjs-vite'
-    | 'sveltekit'
-    | 'vue-vite'
-    | 'vercel-ai-sdk'
-    | 'ai-chat'
-    | 'python-script';
+  base: ProjectBase;
   ruleFiles:
     | 'cursor'
     | 'claude'
@@ -93,21 +81,7 @@ export const runCli = async (): Promise<Project> => {
       new Option(
         '-b --base <template>',
         'The base template to scaffold from',
-      ).choices([
-        'next-js-app-dir',
-        'vite-react',
-        'vite-vanilla',
-        'expo',
-        'bun-react',
-        'tanstack-start',
-        'tanstack-start-with-tanstack-query',
-        'solidjs-vite',
-        'sveltekit',
-        'vue-vite',
-        'vercel-ai-sdk',
-        'ai-chat',
-        'python-script',
-      ]),
+      ).choices(projectBases),
     )
     .addOption(
       new Option('-g --git', 'Create a git repo in the new project').default(

client/packages/create-instant-app/src/env.ts

@@ -1,31 +1,15 @@
 import fs from 'fs-extra';
 import path from 'path';
-import { Project } from './cli.js';
-
-const envNames: Record<Project['base'], string> = {
-  'next-js-app-dir': 'NEXT_PUBLIC_INSTANT_APP_ID',
-  'vite-react': 'VITE_INSTANT_APP_ID',
-  'vite-vanilla': 'VITE_INSTANT_APP_ID',
-  expo: 'EXPO_PUBLIC_INSTANT_APP_ID',
-  'tanstack-start': 'VITE_INSTANT_APP_ID',
-  'bun-react': 'BUN_PUBLIC_INSTANT_APP_ID',
-  'solidjs-vite': 'VITE_INSTANT_APP_ID',
-  sveltekit: 'VITE_INSTANT_APP_ID',
-  'vue-vite': 'VITE_INSTANT_APP_ID',
-  'tanstack-start-with-tanstack-query': 'VITE_INSTANT_APP_ID',
-  'vercel-ai-sdk': 'NEXT_PUBLIC_INSTANT_APP_ID',
-  'ai-chat': 'NEXT_PUBLIC_INSTANT_APP_ID',
-  'python-script': 'INSTANT_APP_ID',
-};
+import { projectBaseConfig, type ProjectBase } from './projectBase.js';
 
 export const applyEnvFile = (
-  project: Project,
+  base: ProjectBase,
   projectDir: string,
   appId: string,
   adminToken: string,
 ) => {
   const envPath = path.join(projectDir, '.env');
-  const envVarName = envNames[project.base];
+  const envVarName = projectBaseConfig[base].appIdEnvName;
   const envContent = `${envVarName}=${appId}\nINSTANT_APP_ADMIN_TOKEN=${adminToken}`;
 
   fs.writeFileSync(envPath, envContent);

client/packages/create-instant-app/src/index.ts

@@ -24,6 +24,7 @@ import { parseNameAndPath } from './utils/validateAppName.js';
 import { execa } from 'execa';
 import { getRules, getSchema } from './utils/appConfig.js';
 import { printAppCreateResult } from './utils/printAppCreateResult.js';
+import { applyBackendConfig } from './backendConfig.js';
 
 const main = async () => {
   if (
@@ -44,6 +45,14 @@ const main = async () => {
 
   const projectDir = await scaffoldBase(project, appDir);
 
+  if (process.env.INSTANT_CLI_API_URI) {
+    applyBackendConfig(
+      project.base,
+      projectDir,
+      process.env.INSTANT_CLI_API_URI,
+    );
+  }
+
   addRuleFiles({
     projectDir,
     ruleFilesToAdd: project.ruleFiles,
@@ -68,7 +77,7 @@ const main = async () => {
   printAppCreateResult(possibleAppTokenPair);
   if (possibleAppTokenPair) {
     applyEnvFile(
-      project,
+      project.base,
       projectDir,
       possibleAppTokenPair.appId,
       possibleAppTokenPair.adminToken,