docs(solid-start): convex + better-auth example (#5796)

Author: brenelz

docs/start/config.json

@@ -338,6 +338,10 @@
               "label": "Basic + Supabase",
               "to": "framework/solid/examples/start-basic-supabase"
             },
+            {
+              "label": "Bare + Convex + Better Auth",
+              "to": "framework/solid/examples/start-convex-better-auth"
+            },
             {
               "label": "Cloudflare Vite Plugin",
               "to": "framework/solid/examples/start-basic-cloudflare"

examples/solid/start-convex-better-auth/.env.example

@@ -0,0 +1,10 @@
+# Deployment used by `npx convex dev`
+CONVEX_DEPLOYMENT=
+
+VITE_CONVEX_URL=
+
+# Same as VITE_CONVEX_URL but ends in .site
+VITE_CONVEX_SITE_URL=
+
+# Your local site URL
+SITE_URL=http://localhost:3000

examples/solid/start-convex-better-auth/.gitignore

@@ -0,0 +1,3 @@
+
+.env.local
+/convex/_generated/

examples/solid/start-convex-better-auth/README.md

@@ -0,0 +1,15 @@
+### Guide
+
+Rename .env.example to .env.local
+
+Run
+
+- `pnpm i`
+- `pnpx convex dev`
+- `pnpx convex env set SITE_URL http://localhost:3000/`
+- `pnpx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)`
+- `pnpx convex dev` - takes up one terminal
+
+In a separate terminal run
+
+- `pnpm run dev`

examples/solid/start-convex-better-auth/convex/README.md

@@ -0,0 +1,90 @@
+# Welcome to your Convex functions directory!
+
+Write your Convex functions here.
+See https://docs.convex.dev/functions for more.
+
+A query function that takes two arguments looks like:
+
+```ts
+// functions.js
+import { query } from './_generated/server'
+import { v } from 'convex/values'
+
+export const myQueryFunction = query({
+  // Validators for arguments.
+  args: {
+    first: v.number(),
+    second: v.string(),
+  },
+
+  // Function implementation.
+  handler: async (ctx, args) => {
+    // Read the database as many times as you need here.
+    // See https://docs.convex.dev/database/reading-data.
+    const documents = await ctx.db.query('tablename').collect()
+
+    // Arguments passed from the client are properties of the args object.
+    console.log(args.first, args.second)
+
+    // Write arbitrary JavaScript here: filter, aggregate, build derived data,
+    // remove non-public properties, or create new objects.
+    return documents
+  },
+})
+```
+
+Using this query function in a React component looks like:
+
+```ts
+const data = useQuery(api.functions.myQueryFunction, {
+  first: 10,
+  second: 'hello',
+})
+```
+
+A mutation function looks like:
+
+```ts
+// functions.js
+import { mutation } from './_generated/server'
+import { v } from 'convex/values'
+
+export const myMutationFunction = mutation({
+  // Validators for arguments.
+  args: {
+    first: v.string(),
+    second: v.string(),
+  },
+
+  // Function implementation.
+  handler: async (ctx, args) => {
+    // Insert or modify documents in the database here.
+    // Mutations can also read from the database like queries.
+    // See https://docs.convex.dev/database/writing-data.
+    const message = { body: args.first, author: args.second }
+    const id = await ctx.db.insert('messages', message)
+
+    // Optionally, return a value from your mutation.
+    return await ctx.db.get(id)
+  },
+})
+```
+
+Using this mutation function in a React component looks like:
+
+```ts
+const mutation = useMutation(api.functions.myMutationFunction)
+function handleButtonPress() {
+  // fire and forget, the most common way to use mutations
+  mutation({ first: 'Hello!', second: 'me' })
+  // OR
+  // use the result once the mutation has completed
+  mutation({ first: 'Hello!', second: 'me' }).then((result) =>
+    console.log(result),
+  )
+}
+```
+
+Use the Convex CLI to push your functions to a deployment. See everything
+the Convex CLI can do by running `npx convex -h` in your project root
+directory. To learn more, launch the docs with `npx convex docs`.

examples/solid/start-convex-better-auth/convex/auth.config.ts

@@ -0,0 +1,8 @@
+export default {
+  providers: [
+    {
+      domain: process.env.CONVEX_SITE_URL,
+      applicationID: 'convex',
+    },
+  ],
+}

examples/solid/start-convex-better-auth/convex/auth.ts

@@ -0,0 +1,46 @@
+import { createClient } from '@convex-dev/better-auth'
+import { convex } from '@convex-dev/better-auth/plugins'
+import { betterAuth } from 'better-auth'
+import { components } from './_generated/api'
+import { query } from './_generated/server'
+import type { GenericCtx } from '@convex-dev/better-auth'
+import type { DataModel } from './_generated/dataModel'
+
+const siteUrl = process.env.SITE_URL!
+
+// The component client has methods needed for integrating Convex with Better Auth,
+// as well as helper methods for general use.
+export const authComponent = createClient<DataModel>(components.betterAuth)
+
+export const createAuth = (
+  ctx: GenericCtx<DataModel>,
+  { optionsOnly } = { optionsOnly: false },
+) => {
+  return betterAuth({
+    // disable logging when createAuth is called just to generate options.
+    // this is not required, but there's a lot of noise in logs without it.
+    logger: {
+      disabled: optionsOnly,
+    },
+    baseURL: siteUrl,
+    database: authComponent.adapter(ctx),
+    // Configure simple, non-verified email/password to get started
+    emailAndPassword: {
+      enabled: true,
+      requireEmailVerification: false,
+    },
+    plugins: [
+      // The Convex plugin is required for Convex compatibility
+      convex({ jwtExpirationSeconds: 60 * 60 * 24 }),
+    ],
+  })
+}
+
+// Example function for getting the current user
+// Feel free to edit, omit, etc.
+export const getCurrentUser = query({
+  args: {},
+  handler: async (ctx) => {
+    return authComponent.getAuthUser(ctx)
+  },
+})

examples/solid/start-convex-better-auth/convex/convex.config.ts

@@ -0,0 +1,6 @@
+import { defineApp } from 'convex/server'
+import betterAuth from '@convex-dev/better-auth/convex.config'
+
+const app = defineApp()
+app.use(betterAuth)
+export default app

examples/solid/start-convex-better-auth/convex/http.ts

@@ -0,0 +1,6 @@
+import { httpRouter } from 'convex/server'
+import { authComponent, createAuth } from './auth'
+
+const http = httpRouter()
+authComponent.registerRoutes(http, createAuth)
+export default http

examples/solid/start-convex-better-auth/convex/myFunctions.ts

@@ -0,0 +1,94 @@
+import { v } from 'convex/values'
+import { action, mutation, query } from './_generated/server'
+import { api } from './_generated/api'
+import { authComponent } from './auth'
+
+// Write your Convex functions in any file inside this directory (`convex`).
+// See https://docs.convex.dev/functions for more.
+
+// You can read data from the database via a query:
+export const listNumbers = query({
+  // Validators for arguments.
+  args: {
+    count: v.number(),
+  },
+
+  // Query implementation.
+  handler: async (ctx, args) => {
+    // Get the current authenticated user
+    const authUser = await authComponent.getAuthUser(ctx)
+    if (!authUser._id) {
+      throw new Error('User must be authenticated to list random numbers')
+    }
+
+    // Read the database as many times as you need here.
+    // See https://docs.convex.dev/database/reading-data.
+    const numbers = await ctx.db
+      .query('numbers')
+      .withIndex('userId', (q) => q.eq('userId', authUser._id))
+      // Ordered by _creationTime, return most recent
+      .order('desc')
+      .take(args.count)
+    return {
+      viewer: (await ctx.auth.getUserIdentity())?.name ?? null,
+      numbers: numbers.reverse().map((number) => number.value),
+    }
+  },
+})
+
+// You can write data to the database via a mutation:
+export const addNumber = mutation({
+  // Validators for arguments.
+  args: {
+    value: v.number(),
+  },
+
+  // Mutation implementation.
+  handler: async (ctx, args) => {
+    // Get the current authenticated user
+    const authUser = await authComponent.getAuthUser(ctx)
+    if (!authUser._id) {
+      throw new Error('User must be authenticated to create a random number')
+    }
+
+    // Insert or modify documents in the database here.
+    // Mutations can also read from the database like queries.
+    // See https://docs.convex.dev/database/writing-data.
+
+    const id = await ctx.db.insert('numbers', {
+      value: args.value,
+      userId: authUser._id,
+    })
+
+    console.log('Added new document with id:', id)
+    // Optionally, return a value from your mutation.
+    // return id;
+  },
+})
+
+// You can fetch data from and send data to third-party APIs via an action:
+export const myAction = action({
+  // Validators for arguments.
+  args: {
+    first: v.number(),
+  },
+
+  // Action implementation.
+  handler: async (ctx, args) => {
+    // // Use the browser-like `fetch` API to send HTTP requests.
+    // // See https://docs.convex.dev/functions/actions#calling-third-party-apis-and-using-npm-packages.
+    // const response = await ctx.fetch("https://api.thirdpartyservice.com");
+    // const data = await response.json();
+
+    // // Query data by running Convex queries.
+    const data = await ctx.runQuery(api.myFunctions.listNumbers, {
+      count: 10,
+    })
+    console.log(data)
+
+    // // Write data by running Convex mutations.
+    await ctx.runMutation(api.myFunctions.addNumber, {
+      value: args.first,
+    })
+  },
+})