Link to more components from relevant places (#36504)

Create a new card type that highlights components in docs. Use it to link to relevant components from various parts of the doc.

GitOrigin-RevId: 3471b7b2304ef792540edca2005155f349f63c8e

Author: ikhare

npm-packages/docs/docs/agents.mdx

@@ -25,6 +25,25 @@ The [Agent](https://www.convex.dev/components/agent) and
 [Workflow](https://www.convex.dev/components/workflow) components can be used
 together to create powerful long running agents with memory.
 
+import { ComponentCardList } from "@site/src/components/ComponentCard";
+
+<ComponentCardList
+  items={[
+    {
+      title: "Agent",
+      description:
+        "Agents organize your AI workflows into units, with message history and vector search built in.",
+      href: "https://www.convex.dev/components/agent",
+    },
+    {
+      title: "Workflow",
+      description:
+        "Simplify programming long running code flows. Workflows execute durably with configurable retries and delays.",
+      href: "https://www.convex.dev/components/workflow",
+    },
+  ]}
+/>
+
 Learn more by reading:
 [AI Agents with Built-in Memory](https://stack.convex.dev/ai-agents).
 
@@ -90,16 +109,25 @@ export const supportAgentWorkflow = workflow.define({
 Convex also provides other components to help you build reliable AI
 applications.
 
-The
-[Persistent Text Streaming](https://www.convex.dev/components/persistent-text-streaming)
-component provides a React hook for streaming text from HTTP actions while
-simultaneously storing the data in the database. This persistence allows the
-text to be accessed after the stream ends or by other users.
-
-The [Action Retrier](https://www.convex.dev/components/retrier) Component is
-useful for one of flaky AI calls that you want to automatically retry. It will
-run the action and retry it on failure, sleeping with exponential backoff, until
-the action succeeds or the maximum number of retries is reached.
-
-The [Workpool](https://www.convex.dev/components/workpool) Component lets you
-create tiers of parallelism to handle large number of external requests.
+<ComponentCardList
+  items={[
+    {
+      title: "Persistent Text Streaming",
+      description:
+        "Stream text from HTTP actions while storing data in the database, enabling access after the stream ends or by other users.",
+      href: "https://www.convex.dev/components/persistent-text-streaming",
+    },
+    {
+      title: "Action Retrier",
+      description:
+        "Add reliability to unreliable external service calls. Retry idempotent calls with exponential backoff until success.",
+      href: "https://www.convex.dev/components/retrier",
+    },
+    {
+      title: "Workpool",
+      description:
+        "Create tiers of parallelism to manage and prioritize large numbers of external requests efficiently.",
+      href: "https://www.convex.dev/components/workpool",
+    },
+  ]}
+/>

npm-packages/docs/docs/cspell.json

@@ -20,6 +20,7 @@
     "codegen",
     "convexapp",
     "convexmobile",
+    "cronspec",
     "dall",
     "Dall",
     "Daria",
@@ -114,8 +115,8 @@
     "venv",
     "vueuse",
     "webapps",
-    "websockets",
     "webm",
+    "websockets",
     "whsec",
     "Workpool",
     "yourclientid",

npm-packages/docs/docs/database/writing-data.mdx

@@ -7,6 +7,7 @@ import insertExample from "!!raw-loader!@site/../private-demos/snippets/convex/w
 import patchExample from "!!raw-loader!@site/../private-demos/snippets/convex/writingDataPatch.ts";
 import replaceExample from "!!raw-loader!@site/../private-demos/snippets/convex/writingDataReplace.ts";
 import deleteExample from "!!raw-loader!@site/../private-demos/snippets/convex/writingDataDelete.ts";
+import { ComponentCardList } from "@site/src/components/ComponentCard";
 
 [Mutations](/docs/functions/mutation-functions.mdx) can insert, update, and
 remove data from database tables.
@@ -129,6 +130,22 @@ export const bulkInsertProducts = mutation({
 });
 ````
 
+## Migrations
+
+Database migrations are done through the migration component. The component is
+designed to run online migrations to safely evolve your database schema over
+time. It allows you to resume from failures, and validate changes with dry runs.
+
+<ComponentCardList
+  items={[
+    {
+      title: "Migrations",
+      description: "Framework for long running data migrations of live data.",
+      href: "https://www.convex.dev/components/migrations",
+    },
+  ]}
+/>
+
 ## Write performance and limits
 
 To prevent accidental writes of large amounts of records, queries and mutations

npm-packages/docs/docs/scheduling.mdx

@@ -4,6 +4,8 @@ hide_table_of_contents: true
 pagination_prev: auth
 ---
 
+import { ComponentCardList } from "@site/src/components/ComponentCard";
+
 Convex lets you easily schedule a function to run once or repeatedly in the
 future. This allows you to build durable workflows like sending a welcome email
 a day after someone joins or regularly reconciling your accounts with Stripe.
@@ -15,4 +17,39 @@ Convex provides two different features for scheduling:
 - [Cron Jobs](/docs/scheduling/cron-jobs.mdx) schedule functions to run on a
   recurring basis, such as daily.
 
+## Durable function components
+
+Built-in scheduled functions and crons work well for simpler apps and workflows.
+If you're operating at high scale or need more specific guarantees, use the
+following higher-level [components](/docs/components.mdx) for durable functions.
+
+<ComponentCardList
+  items={[
+    {
+      title: "Workpool",
+      description:
+        "Workpool give critical tasks priority by organizing async operations into separate, customizable queues.",
+      href: "https://www.convex.dev/components/workpool",
+    },
+    {
+      title: "Workflow",
+      description:
+        "Simplify programming long running code flows. Workflows execute durably with configurable retries and delays.",
+      href: "https://www.convex.dev/components/workflow",
+    },
+    {
+      title: "Action Retrier",
+      description:
+        "Add reliability to an unreliable external service. Retry idempotent calls a set number of times.",
+      href: "https://www.convex.dev/components/retrier",
+    },
+    {
+      title: "Crons",
+      description:
+        "Use cronspec to run functions on a repeated schedule at runtime.",
+      href: "https://www.convex.dev/components/crons",
+    },
+  ]}
+/>
+
 <StackPosts query="scheduler" />

npm-packages/docs/src/components/ComponentCard.tsx

@@ -0,0 +1,58 @@
+import React from "react";
+import Link from "@docusaurus/Link";
+import Heading from "@theme/Heading";
+
+type ComponentCardItem = {
+  href?: string;
+  title: string;
+  description: string;
+};
+
+const ComponentIcon = () => (
+  <div className="component-card-header">
+    <svg
+      width="15"
+      height="15"
+      viewBox="-1 0 13 10"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className="component-card-icon"
+    >
+      <path
+        d="M9.00954 3.1018C9.00954 3.25833 9.08285 3.40583 9.20762 3.50035C9.33239 3.59487 9.49423 3.62551 9.64491 3.58313C9.764 3.54963 9.88902 3.53335 10.0308 3.53335H10.0361C10.8473 3.53335 11.5054 4.19146 11.5054 5.00263C11.5054 5.81381 10.8473 6.47192 10.0361 6.47192C9.90304 6.47192 9.77217 6.45267 9.64491 6.41688C9.49423 6.3745 9.33239 6.40513 9.20762 6.49965C9.08285 6.59417 9.00954 6.74167 9.00954 6.8982V8.75208C9.00954 9.02823 8.78568 9.25208 8.50954 9.25208H1.00537C0.729228 9.25208 0.505371 9.02823 0.505371 8.75209V1.24792C0.505371 0.971774 0.729229 0.747917 1.00537 0.747917H2.9422C2.873 1.22601 2.93994 1.69202 3.15997 2.08387C3.47318 2.64168 4.05361 2.96989 4.77062 2.96989C5.49213 2.96989 6.05944 2.6369 6.35615 2.07137C6.56128 1.68036 6.61652 1.21869 6.54991 0.747917H8.50954C8.78568 0.747917 9.00954 0.971775 9.00954 1.24792V3.1018Z"
+        stroke="currentColor"
+        strokeLinejoin="round"
+      />
+    </svg>
+    <span className="component-card-label">Convex component</span>
+  </div>
+);
+
+export function ComponentCard({ item }: { item: ComponentCardItem }) {
+  const CardWrapper = item.href ? Link : "div";
+
+  return (
+    <CardWrapper
+      {...(item.href ? { href: item.href } : {})}
+      className="component-card"
+    >
+      <div className="component-card-content">
+        <ComponentIcon />
+        <Heading as="h3" className="component-card-title">
+          {item.title}
+        </Heading>
+        <p className="component-card-description">{item.description}</p>
+      </div>
+    </CardWrapper>
+  );
+}
+
+export function ComponentCardList({ items }: { items: ComponentCardItem[] }) {
+  return (
+    <div className="component-cards">
+      {items.map((item, index) => (
+        <ComponentCard key={index} item={item} />
+      ))}
+    </div>
+  );
+}

npm-packages/docs/src/css/custom.css

@@ -366,8 +366,65 @@ article code {
 
 .component-cards {
   display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.component-card {
+  display: block;
+  padding: 1.5rem;
+  border-radius: var(--ifm-card-border-radius);
+  text-decoration: none;
+  border: 1px solid var(--ifm-toc-border-color);
+  background: var(--ifm-background-color);
+  min-height: 130px;
+  box-shadow: none;
+}
+
+.component-card:hover {
+  box-shadow: none;
+  background-color: var(--ifm-menu-color-background-active);
+  color: var(--ifm-font-color-base);
+  text-decoration: none;
+}
+
+.component-card-content {
+  display: flex;
+  flex-direction: column;
   gap: 1rem;
-  margin: 1.5rem 0 2.5rem;
+}
+
+.component-card-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.component-card-icon {
+  color: var(--ifm-navbar-link-color);
+  flex-shrink: 0;
+}
+
+.component-card-label {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  font-weight: 500;
+}
+
+.component-card-title {
+  margin: 0;
+  font-size: 1.125rem;
+  color: var(--ifm-heading-color);
+}
+
+.component-card-description {
+  margin: 0;
+  color: var(--ifm-color-emphasis-700);
+  line-height: 1.5;
+  font-size: 1rem;
 }
 
 /* This magic number 462 is the size of the article div container as rendered */