component api

Author: ianmacartney

.cursor/rules/convex_rules.mdc

@@ -14,3 +14,4 @@ node_modules
 react/package.json
 # npm pack output
 *.tgz
+*.tsbuildinfo

.gitignore

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/convex/schemas/convex.schema.json",
+  "functions": "example/convex"
+}

convex.json

@@ -1,45 +1,81 @@
 import globals from "globals";
 import pluginJs from "@eslint/js";
 import tseslint from "typescript-eslint";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
 
 export default [
-  { files: ["src/**/*.{js,mjs,cjs,ts,tsx}"] },
   {
     ignores: [
       "dist/**",
       "eslint.config.js",
-      "example/eslint.config.js",
+      "vitest.config.ts",
       "**/_generated/",
       "node10stubs.mjs",
     ],
   },
   {
+    files: ["src/**/*.{js,mjs,cjs,ts,tsx}", "example/**/*.{js,mjs,cjs,ts,tsx}"],
     languageOptions: {
-      globals: globals.worker,
       parser: tseslint.parser,
-
       parserOptions: {
-        project: ["./tsconfig.json", "./example/tsconfig.json"],
-        tsconfigRootDir: ".",
+        project: [
+          "./tsconfig.json",
+          "./example/tsconfig.json",
+          "./example/convex/tsconfig.json",
+        ],
+        tsconfigRootDir: import.meta.dirname,
       },
     },
   },
   pluginJs.configs.recommended,
   ...tseslint.configs.recommended,
+  // Convex code - Worker environment
   {
+    files: ["src/**/*.{ts,tsx}", "example/convex/**/*.{ts,tsx}"],
+    ignores: ["src/react/**"],
+    languageOptions: {
+      globals: globals.worker,
+    },
     rules: {
       "@typescript-eslint/no-floating-promises": "error",
-      "@typescript-eslint/consistent-type-imports": [
+      "@typescript-eslint/no-explicit-any": "off",
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+      "@typescript-eslint/no-unused-expressions": [
         "error",
         {
-          prefer: "type-imports",
-          fixStyle: "separate-type-imports",
-          disallowTypeAnnotations: false,
+          allowShortCircuit: true,
+          allowTernary: true,
+          allowTaggedTemplates: true,
         },
       ],
-      "eslint-comments/no-unused-disable": "off",
-
-      // allow (_arg: number) => {} and const _foo = 1;
+    },
+  },
+  // React app code - Browser environment
+  {
+    files: ["src/react/**/*.{ts,tsx}", "example/src/**/*.{ts,tsx}"],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      "react-hooks": reactHooks,
+      "react-refresh": reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      "react-refresh/only-export-components": [
+        "warn",
+        { allowConstantExport: true },
+      ],
+      "@typescript-eslint/no-explicit-any": "off",
       "no-unused-vars": "off",
       "@typescript-eslint/no-unused-vars": [
         "warn",
@@ -50,4 +86,14 @@ export default [
       ],
     },
   },
+  // Example config files (vite.config.ts, etc.) - Node environment
+  {
+    files: ["example/vite.config.ts", "example/**/*.config.{js,ts}"],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.browser,
+      },
+    },
+  },
 ];

eslint.config.js

@@ -18,27 +18,35 @@ import type {
   FunctionReference,
 } from "convex/server";
 
+declare const fullApi: ApiFromModules<{
+  crons: typeof crons;
+  example: typeof example;
+  http: typeof http;
+}>;
+
 /**
- * A utility for referencing Convex functions in your app's API.
+ * A utility for referencing Convex functions in your app's public API.
  *
  * Usage:
  * ```js
  * const myFunctionReference = api.myModule.myFunction;
  * ```
  */
-declare const fullApi: ApiFromModules<{
-  crons: typeof crons;
-  example: typeof example;
-  http: typeof http;
-}>;
-declare const fullApiWithMounts: typeof fullApi;
-
 export declare const api: FilterApi<
-  typeof fullApiWithMounts,
+  typeof fullApi,
   FunctionReference<any, "public">
 >;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
 export declare const internal: FilterApi<
-  typeof fullApiWithMounts,
+  typeof fullApi,
   FunctionReference<any, "internal">
 >;
 

example/convex/_generated/api.d.ts

@@ -1,30 +1,19 @@
 {
-  /* This TypeScript project config describes the environment that
-   * Convex functions run in and is used to typecheck them.
-   * You can modify it, but some settings required to use Convex.
-   */
   "compilerOptions": {
-    /* These settings are not required by Convex and can be modified. */
     "allowJs": true,
     "strict": true,
     "skipLibCheck": true,
-
-    /* These compiler options are required by Convex */
     "target": "ESNext",
-    "lib": ["ES2021", "dom", "ESNext.Array"],
+    "lib": ["ES2021", "dom", "DOM.Iterable", "ESNext.Array"],
     "forceConsistentCasingInFileNames": true,
     "allowSyntheticDefaultImports": true,
+    "verbatimModuleSyntax": true,
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "isolatedModules": true,
     "noEmit": true,
-
-    /* This should only be used in this example. Real apps should not attempt
-     * to compile TypeScript because differences between tsconfig.json files can
-     * cause the code to be compiled differently.
-     */
-    "customConditions": ["@convex-dev/component-source"]
+    "jsx": "react-jsx"
   },
-  "include": ["./**/*"],
+  "include": [".*"],
   "exclude": ["./_generated"]
 }

example/convex/tsconfig.json

@@ -9,10 +9,10 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "resolveJsonModule": true,
+    "exactOptionalPropertyTypes": true,
     "isolatedModules": true,
-    "allowImportingTsExtensions": true,
-    "noEmit": true,
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
+    "noEmit": true
   },
-  "include": ["./src", "vite.config.ts", "./convex"]
+  "include": ["./src", "vite.config.ts"]
 }

example/eslint.config.js

@@ -15,51 +15,58 @@
   ],
   "type": "module",
   "scripts": {
-    "example": "cd example && npm run dev",
-    "dev": "run-p -r 'example' 'build:watch'",
-    "dashboard": "cd example && npx convex dashboard",
-    "all": "run-p -r 'example' 'build:watch' 'test:watch'",
-    "setup": "npm i && npm run build && cd example && npm i && npx convex dev --once --live-component-sources --typecheck-components",
-    "build:watch": "npx chokidar 'tsconfig*.json' 'src/**/*.ts' -c 'npm run build' --initial",
-    "build": "tsc --project ./tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-    "alpha": "npm run clean && npm run build && run-p test lint typecheck && npm version prerelease --preid alpha && npm publish --tag alpha && git push --tags",
-    "release": "npm run clean && npm run build && run-p test lint typecheck && npm version patch && npm publish && git push --tags",
-    "clean": "rm -rf dist tsconfig.build.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
-    "prepare": "npm run build",
-    "prepack": "node node10stubs.mjs",
-    "postpack": "node node10stubs.mjs --cleanup",
-    "test": "vitest run --typecheck --config ./src/vitest.config.ts",
-    "test:watch": "vitest --typecheck --config ./src/vitest.config.ts",
-    "test:debug": "vitest --inspect-brk --no-file-parallelism --config ./src/vitest.config.ts",
+    "dev": "run-p -r 'dev:*'",
+    "dev:backend": "convex dev --typecheck-components",
+    "dev:frontend": "cd example && vite --clearScreen false",
+    "dev:build": "npx chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npx convex codegen --component ./src/component && npm run build' --initial",
+    "predev": "npm run dev:backend -- --until-success",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "build": "tsc --project ./tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint src && eslint example",
+    "all": "run-p -r 'dev:*' 'test:watch'",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
     "test:coverage": "vitest run --coverage --coverage.reporter=text",
-    "lint": "eslint src"
+    "attw": "attw $(npm pack -s) --exclude-entrypoints ./convex.config --profile esm-only",
+    "prepare": "npm run build",
+    "alpha": "npm run clean && npm ci && run-p test lint typecheck attw && npm version prerelease --preid alpha && npm publish --tag alpha && git push --tags",
+    "release": "npm run clean && npm ci && run-p test lint typecheck attw && npm version patch && npm publish && git push --tags",
+    "version": "pbcopy <<<$npm_package_version; vim CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
   },
   "files": [
     "dist",
-    "src",
-    "react"
+    "src"
   ],
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
     "./convex.config": {
       "types": "./dist/component/convex.config.d.ts",
       "default": "./dist/component/convex.config.js"
     }
   },
   "peerDependencies": {
-    "convex": "^1.23.0",
+    "convex": "^1.24.8",
     "convex-helpers": "^0.1.99"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.38.0",
-    "@types/node": "^22.18.13",
+    "@types/node": "20.19.24",
     "chokidar-cli": "^3.0.0",
     "convex": "1.25.4",
     "convex-test": "^0.0.33",
@@ -76,7 +83,6 @@
     "typescript-eslint": "^8.46.2",
     "vitest": "^3.2.4"
   },
-  "main": "./dist/client/index.js",
   "types": "./dist/client/index.d.ts",
   "module": "./dist/client/index.js",
   "dependencies": {