use component api

.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Test and lint
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  check:
+    name: Test and lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+
+      - name: Node setup
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          cache-dependency-path: package.json
+          node-version: "20.x"
+          cache: "npm"
+
+      - name: Install and build
+        run: |
+          npm i
+          npm run build
+      - name: Publish package for testing branch
+        run: npx pkg-pr-new publish || echo "Have you set up pkg-pr-new for this repo?"
+      - name: Test
+        run: |
+          npm run test
+          npm run typecheck
+          npm run lint

.gitignore

@@ -9,8 +9,6 @@ dist-ssr
 explorations
 node_modules
 .eslintcache
-# components are libraries!
-# package-lock.json
 
 # this is a package-json-redirect stub dir, see https://github.com/andrewbranch/example-subpath-exports-ts-compat?tab=readme-ov-file
 react/package.json

.prettierrc.json

@@ -1,4 +1,4 @@
 {
-  "proseWrap": "always",
-  "trailingComma": "all"
+  "trailingComma": "all",
+  "proseWrap": "always"
 }

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0
+
+- Adds /test and /\_generated/component.js entrypoints
+- Drops commonjs support
+- Improves source mapping for generated files
+- Changes to a statically generated component API
+
 ## 0.2.12
 
 - Capture tool errors in the message

CONTRIBUTING.md

@@ -3,7 +3,7 @@
 ## Running locally
 
 ```sh
-npm run setup
+npm i
 npm run dev
 ```
 
@@ -12,9 +12,9 @@ npm run dev
 ```sh
 npm run clean
 npm run build
-npm run test
 npm run typecheck
 npm run lint
+npm run test
 ```
 
 ## Deploying
@@ -23,50 +23,18 @@ npm run lint
 
 ```sh
 npm run clean
-npm run build
+npm ci
 npm pack
 ```
 
 ### Deploying a new version
 
-Patch release:
-
 ```sh
 npm run release
 ```
 
-#### Alpha release
-
-The same as above, but it requires extra flags so the release is only installed
-with `@alpha`:
+or for alpha release:
 
 ```sh
 npm run alpha
 ```
-
-# Idea/ feature backlog:
-
-- Convenience function to create a thread by copying an existing thread (fork)
-- Allow aborting normal generateText
-- Improve the demo to show more of the features & have nicer UI
-  - Add an example of using tracing / telemetry.
-- Add an example of using MCP with the Agent.
-- Automatically turn big text content into a file when saving a message and keep
-  as a fileId. Re-hydrate it when reading out for generation.
-
-## Playground feature wishlist (contributions welcome!)
-
-- List all threads instead of user dropdown.
-  - If a user is logged in, use their userId instead of the apiKey for auth &
-    return only their threads.
-- Show threads that aren't associated with a user as "no user" in the dropdown.
-- Add a "fork thread" button in the right message detail sidebar.
-- Add a "retry" button to regenerate a response while tuning the prompt/context.
-- Show the contextual messages with their rank in vector & text search, to get a
-  sense of what is being found via text vs. vector vs. recency search.
-- Show the agent's default context & storage options.
-- Show tools and allow calling them directly.
-- Generate objects from the UI, not just text.
-- Archive messages
-- Configure which tools are available when doing one-off messaging.
-- Trace older messages for what exact context they used.

convex.json

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

docs/context.mdx

@@ -131,7 +131,7 @@ const result = await agent.generateText(
       const related = await getRelatedThreadMessages(ctx, args.threadId);
       return [
         // Summarize or truncate context messages if they are too long.
-        ...await summarizeOrTruncateIfTooLong(related),
+        ...(await summarizeOrTruncateIfTooLong(related)),
         ...relevantSearch,
         ...userMemories,
         ...sampleMessages,

docs/debugging.mdx

@@ -32,8 +32,8 @@ const supportAgent = new Agent(components.agent, {
 
 ## Logging the context messages via the contextHandler
 
-You can log the context messages via the contextHandler, if you're curious
-what exactly the LLM is receiving.
+You can log the context messages via the contextHandler, if you're curious what
+exactly the LLM is receiving.
 
 ```ts
 const supportAgent = new Agent(components.agent, {

eslint.config.js

@@ -1,56 +1,98 @@
 import globals from "globals";
 import pluginJs from "@eslint/js";
 import tseslint from "typescript-eslint";
-import reactPlugin from "eslint-plugin-react";
 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", "setup.cjs", "**/_generated/"],
+    ignores: [
+      "dist/**",
+      "example/dist/**",
+      "playground/dist/**",
+      "*.config.js",
+      "setup.cjs",
+      "example/**/*.config.{cjs,js,ts}",
+      "playground/**/*.config.{js,ts}",
+      "playground/bin/agent-playground.cjs",
+      "**/_generated/",
+      "node10stubs.mjs",
+    ],
   },
   {
+    files: [
+      "src/**/*.{js,mjs,cjs,ts,tsx}",
+      "example/**/*.{js,mjs,cjs,ts,tsx}",
+      "playground/**/*.{js,mjs,cjs,ts,tsx}",
+    ],
     languageOptions: {
-      globals: globals.worker,
       parser: tseslint.parser,
-
       parserOptions: {
-        project: true,
+        project: [
+          "./tsconfig.json",
+          "./example/tsconfig.json",
+          "./example/convex/tsconfig.json",
+          "./playground/tsconfig.app.json",
+          "./playground/tsconfig.node.json",
+        ],
         tsconfigRootDir: import.meta.dirname,
       },
     },
   },
   pluginJs.configs.recommended,
   ...tseslint.configs.recommended,
+  // Convex code - Worker environment
   {
     files: [
-      "src/react/**/*.{jsx,tsx}",
-      "src/react/**/*.js",
-      "src/react/**/*.ts",
+      "src/**/*.{ts,tsx}",
+      "example/convex/**/*.{ts,tsx}",
+      "playground/convex/**/*.{ts,tsx}",
     ],
-    plugins: { react: reactPlugin, "react-hooks": reactHooks },
-    settings: {
-      react: {
-        version: "detect",
-      },
+    ignores: ["src/react/**"],
+    languageOptions: {
+      globals: globals.worker,
     },
     rules: {
-      ...reactPlugin.configs["recommended"].rules,
-      "react/jsx-uses-react": "off",
-      "react/react-in-jsx-scope": "off",
-      "react/prop-types": "off",
-      "react-hooks/rules-of-hooks": "error",
-      "react-hooks/exhaustive-deps": "warn",
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-explicit-any": "off",
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+      "@typescript-eslint/no-unused-expressions": [
+        "error",
+        {
+          allowShortCircuit: true,
+          allowTernary: true,
+          allowTaggedTemplates: true,
+        },
+      ],
     },
   },
+  // React app code - Browser environment
   {
+    files: [
+      "src/react/**/*.{ts,tsx}",
+      "example/ui/**/*.{ts,tsx}",
+      "playground/src/**/*.{ts,tsx}",
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      "react-hooks": reactHooks,
+      "react-refresh": reactRefresh,
+    },
     rules: {
-      "@typescript-eslint/no-floating-promises": "error",
-      "eslint-comments/no-unused-disable": "off",
-
-      // allow (_arg: number) => {} and const _foo = 1;
+      ...reactHooks.configs.recommended.rules,
+      "react-refresh/only-export-components": "off",
+      "@typescript-eslint/no-explicit-any": "off",
       "no-unused-vars": "off",
-      "no-unused-private-class-members": "warn",
       "@typescript-eslint/no-unused-vars": [
         "warn",
         {

example/README.md

@@ -4,17 +4,18 @@ This is an example app that uses the `@convex-dev/agent` package.
 
 See the [Agent docs](https://docs.convex.dev/agents) for documentation.
 
-The backend usage is in `convex/`, with folders to organize usecases.
-The frontend usage is in `ui/`.
+The backend usage is in `convex/`, with folders to organize usecases. The
+frontend usage is in `ui/`.
 
-The example exercises many usecases, with the underlying code organized
-into folders by category.
+The example exercises many usecases, with the underlying code organized into
+folders by category.
 
 The main difference from your app will be:
 
 - What models you use (currently uses `modelsForDemo.ts`)
 - Usage handling - currently configures agents to use `usageHandler.ts`
-- How you handle auth - currently has an example `authorizeThreadAccess` function.
+- How you handle auth - currently has an example `authorizeThreadAccess`
+  function.
 
 ## Running the example