Update Convex example to convex@0.12.0 (#47175)

Updates Convex to 0.12.0

### Improving Documentation or adding/fixing Examples

- [x] The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- [x] Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md

Co-authored-by: Alex Cole <2695197+alexcole@users.noreply.github.com>

examples/convex/README.md

@@ -1,6 +1,6 @@
 # Convex
 
-This example demonstrates the Convex global state management framework.
+This example demonstrates the Convex backend platform.
 
 ## Deploy your own
 

examples/convex/convex/README.md

@@ -5,11 +5,11 @@ https://docs.convex.dev/using/writing-convex-functions for more.
 
 A query function that takes two arguments looks like:
 
-```typescript
-// myQueryFunction.ts
+```javascript
+// myQueryFunction.js
 import { query } from './_generated/server'
 
-export default query(async ({ db }, first: number, second: string) => {
+export default query(async ({ db }, first, second) => {
   // Validate arguments here.
   if (typeof first !== 'number' || first < 0) {
     throw new Error('First argument is not a non-negative number.')
@@ -30,17 +30,17 @@ export default query(async ({ db }, first: number, second: string) => {
 
 Using this query function in a React component looks like:
 
-```typescript
+```javascript
 const data = useQuery('myQueryFunction', 10, 'hello')
 ```
 
 A mutation function looks like:
 
-```typescript
-// myMutationFunction.ts
+```javascript
+// myMutationFunction.js
 import { mutation } from './_generated/server'
 
-export default mutation(async ({ db }, first: string, second: string) => {
+export default mutation(async ({ db }, first, second) => {
   // Validate arguments here.
   if (typeof first !== 'string' || typeof second !== 'string') {
     throw new Error('Both arguments must be strings')
@@ -58,7 +58,7 @@ export default mutation(async ({ db }, first: string, second: string) => {
 
 Using this mutation function in a React component looks like:
 
-```typescript
+```javascript
 const mutation = useMutation('myMutationFunction')
 function handleButtonPress() {
   // fire and forget, the most common way to use mutations

examples/convex/convex/_generated/api.d.ts

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */

examples/convex/convex/_generated/dataModel.d.ts

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */
@@ -24,7 +24,7 @@ export type TableNames = TableNamesInDataModel<DataModel>;
  *
  * @typeParam TableName - A string literal type of the table name (like "users").
  */
-export type Document<TableName extends TableNames> = DocumentByName<
+export type Doc<TableName extends TableNames> = DocumentByName<
   DataModel,
   TableName
 >;

examples/convex/convex/_generated/dataModel.js

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */

examples/convex/convex/_generated/react.d.ts

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */

examples/convex/convex/_generated/react.js

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */

examples/convex/convex/_generated/server.d.ts

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */
@@ -14,6 +14,10 @@ import {
   HttpEndpointBuilderForAPI,
   MutationBuilder,
   QueryBuilderForDataModel,
+  InternalActionBuilderForAPI,
+  InternalMutationBuilder,
+  InternalQueryBuilderForDataModel,
+  CronJobsForAPI,
   ActionCtx as GenericActionCtx,
   HttpEndpointCtx as GenericHttpEndpointCtx,
   MutationCtx as GenericMutationCtx,
@@ -24,6 +28,30 @@ import {
 import type { DataModel } from "./dataModel.js";
 import type { API } from "./api.js";
 
+/**
+ * Returns a cron job scheduler, used to schedule Convex functions to run on a recurring basis.
+ *
+ * ```js
+ * // convex/crons.js
+ * import { cronJobs } from './_generated/server';
+ *
+ * const crons = cronJobs();
+ * crons.weekly(
+ *   "weekly re-engagement email",
+ *   {
+ *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)
+ *     minuteUTC: 30,
+ *   },
+ *   "sendEmails"
+ * )
+ * export default crons;
+ * ```
+ *
+ * @returns The cron job scheduler object. Create this object in `convex/crons.js` and export it
+ * as the default export.
+ */
+export declare const cronJobs: CronJobsForAPI<API>;
+
 /**
  * Define a query in this Convex app's public API.
  *
@@ -34,6 +62,16 @@ import type { API } from "./api.js";
  */
 export declare const query: QueryBuilderForDataModel<DataModel>;
 
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalQuery: InternalQueryBuilderForDataModel<DataModel>;
+
 /**
  * Define a mutation in this Convex app's public API.
  *
@@ -44,6 +82,16 @@ export declare const query: QueryBuilderForDataModel<DataModel>;
  */
 export declare const mutation: MutationBuilder<DataModel, API>;
 
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalMutation: InternalMutationBuilder<DataModel, API>;
+
 /**
  * Define an action in this Convex app's public API.
  *
@@ -59,6 +107,14 @@ export declare const mutation: MutationBuilder<DataModel, API>;
  */
 export declare const action: ActionBuilderForAPI<API>;
 
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives a {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalAction: InternalActionBuilderForAPI<API>;
+
 /**
  * Define an HTTP endpoint.
  *

examples/convex/convex/_generated/server.js

@@ -4,7 +4,7 @@
  *
  * THIS CODE IS AUTOMATICALLY GENERATED.
  *
- * Generated by convex@0.9.1.
+ * Generated by convex@0.12.0.
  * To regenerate, run `npx convex codegen`.
  * @module
  */
@@ -14,6 +14,10 @@ import {
   httpEndpointGeneric,
   queryGeneric,
   mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+  cronJobsGeneric,
 } from "convex/server";
 
 /**
@@ -26,6 +30,16 @@ import {
  */
 export const query = queryGeneric;
 
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery = internalQueryGeneric;
+
 /**
  * Define a mutation in this Convex app's public API.
  *
@@ -36,6 +50,16 @@ export const query = queryGeneric;
  */
 export const mutation = mutationGeneric;
 
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation = internalMutationGeneric;
+
 /**
  * Define an action in this Convex app's public API.
  *
@@ -51,6 +75,14 @@ export const mutation = mutationGeneric;
  */
 export const action = actionGeneric;
 
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives a {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction = internalActionGeneric;
+
 /**
  * Define a Convex HTTP endpoint.
  *
@@ -59,3 +91,27 @@ export const action = actionGeneric;
  * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
  */
 export const httpEndpoint = httpEndpointGeneric;
+
+/**
+ * Returns a cron job scheduler, used to schedule Convex functions to run on a recurring basis.
+ *
+ * ```js
+ * // convex/crons.js
+ * import { cronJobs } from './_generated/server';
+ *
+ * const crons = cronJobs();
+ * crons.weekly(
+ *   "weekly re-engagement email",
+ *   {
+ *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)
+ *     minuteUTC: 30,
+ *   },
+ *   "sendEmails"
+ * )
+ * export default crons;
+ * ```
+ *
+ * @returns The cron job scheduler object. Create this object in `convex/crons.js` and export it
+ * as the default export.
+ */
+export const cronJobs = cronJobsGeneric;

examples/convex/convex/listMessages.ts

@@ -1,6 +1,6 @@
 import { query } from './_generated/server'
-import { Document } from './_generated/dataModel'
+import { Doc } from './_generated/dataModel'
 
-export default query(async ({ db }): Promise<Document<'messages'>[]> => {
+export default query(async ({ db }): Promise<Doc<'messages'>[]> => {
   return await db.query('messages').collect()
 })

examples/convex/convex/sendMessage.ts

@@ -1,6 +1,8 @@
 import { mutation } from './_generated/server'
 
-export default mutation(async ({ db }, body: string, author: string) => {
+export default mutation(
+  async ({ db }, { body, author }: { body: string; author: string }) => {
     const message = { body, author }
     await db.insert('messages', message)
-})
+  }
+)

examples/convex/convex/tsconfig.json

@@ -16,10 +16,8 @@
     "module": "ESNext",
     "moduleResolution": "Node",
     "isolatedModules": true,
-    "noEmit": true,
-    /* Prevents node_modules from adding additional global types e.g. node types */
-    "types": []
+    "noEmit": true
   },
   "include": ["./**/*"],
-  "exclude": ["./_generated", "./actions"]
+  "exclude": ["./_generated"]
 }

examples/convex/package.json

@@ -10,7 +10,7 @@
     "start": "next start"
   },
   "dependencies": {
-    "convex": "0.9.1",
+    "convex": "~0.12.0",
     "next": "latest",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/convex/pages/_app.tsx

@@ -2,7 +2,14 @@ import '../styles/globals.css'
 import type { AppProps } from 'next/app'
 
 import { ConvexProvider, ConvexReactClient } from 'convex/react'
-const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL)
+
+const address = process.env.NEXT_PUBLIC_CONVEX_URL
+if (!address) {
+  throw new Error(
+    'Convex address not found in env. Have you run npx convex dev for a dev deploy or npx convex deploy for prod?'
+  )
+}
+const convex = new ConvexReactClient(address)
 
 function MyApp({ Component, pageProps }: AppProps) {
   return (

examples/convex/pages/index.tsx

@@ -16,7 +16,7 @@ export default function App() {
   async function handleSendMessage(event: FormEvent) {
     event.preventDefault()
     setNewMessageText('')
-    await sendMessage(newMessageText, name)
+    await sendMessage({ body: newMessageText, author: name })
   }
   return (
     <main>