Refactor SDK to encapsulate schema-to-json package

The previous implementation required users to directly import and initialize functions from the `@trigger.dev/schema-to-json` package, which was not the intended user experience. This change refactors the SDK so that all necessary functions and types from `@trigger.dev/schema-to-json` are encapsulated within the `@trigger.dev/*` packages.

- The examples in `usage.ts` have been updated to clearly mark `@trigger.dev/schema-to-json` as an internal-only package.
- Re-export JSON Schema types and conversions in the SDK to improve developer experience (DX).
- Removed unnecessary direct dependencies on `@trigger.dev/schema-to-json` from user-facing code, ensuring initialization and conversion logic is handled internally.
- Replaced instances where users were required to manually perform schema conversions with automatic handling within the SDK for simplification and better maintainability.

Author: ericallam

packages/schema-to-json/examples/usage.ts

@@ -1,9 +1,10 @@
-import { task } from '@trigger.dev/sdk/v3';
-import { z } from 'zod';
+// This file shows how @trigger.dev/schema-to-json is used INTERNALLY by the SDK
+// Regular users should NOT import this package directly!
+
 import { schemaToJsonSchema, type JSONSchema } from '@trigger.dev/schema-to-json';
+import { z } from 'zod';
 
-// Example 1: Using schemaTask (automatic conversion)
-import { schemaTask } from '@trigger.dev/sdk/v3';
+// Example of how the SDK uses this internally:
 
 const userSchema = z.object({
   id: z.string(),
@@ -12,96 +13,69 @@ const userSchema = z.object({
   age: z.number().int().min(0),
 });
 
-export const processUser = schemaTask({
-  id: 'process-user',
-  schema: userSchema,
-  run: async (payload) => {
-    // payload is fully typed based on the schema
-    console.log(`Processing user ${payload.name}`);
-    return { processed: true };
-  },
-});
+// This is what happens internally in the SDK's schemaTask:
+const result = schemaToJsonSchema(userSchema);
+if (result) {
+  console.log('Converted Zod schema to JSON Schema:', result.jsonSchema);
+  console.log('Detected schema type:', result.schemaType);
+  // The SDK then includes this JSON Schema in the task metadata
+}
 
-// Example 2: Using plain task with manual JSON Schema
-export const processOrder = task({
-  id: 'process-order',
-  // Manually provide JSON Schema for the payload
-  payloadSchema: {
-    type: 'object',
-    properties: {
-      orderId: { type: 'string' },
-      items: {
-        type: 'array',
-        items: {
-          type: 'object',
-          properties: {
-            productId: { type: 'string' },
-            quantity: { type: 'integer', minimum: 1 },
-            price: { type: 'number', minimum: 0 },
-          },
-          required: ['productId', 'quantity', 'price'],
-        },
-      },
-      totalAmount: { type: 'number' },
-    },
-    required: ['orderId', 'items', 'totalAmount'],
-  } satisfies JSONSchema,
-  run: async (payload) => {
-    // payload is typed as any, but the schema will be validated at runtime
-    console.log(`Processing order ${payload.orderId}`);
-    return { processed: true };
-  },
-});
+// Example: How different schema libraries are detected and converted
 
-// Example 3: Using plain task with schema conversion
-const orderSchema = z.object({
-  orderId: z.string(),
-  items: z.array(z.object({
-    productId: z.string(),
-    quantity: z.number().int().min(1),
-    price: z.number().min(0),
-  })),
-  totalAmount: z.number(),
+// Yup schema
+import * as y from 'yup';
+const yupSchema = y.object({
+  name: y.string().required(),
+  age: y.number().required(),
 });
 
-// Convert the schema to JSON Schema
-const orderJsonSchema = schemaToJsonSchema(orderSchema);
-
-export const processOrderWithConversion = task({
-  id: 'process-order-converted',
-  // Use the converted JSON Schema
-  payloadSchema: orderJsonSchema?.jsonSchema,
-  run: async (payload) => {
-    // Note: You still need to validate the payload yourself in plain tasks
-    const parsed = orderSchema.parse(payload);
-    console.log(`Processing order ${parsed.orderId}`);
-    return { processed: true };
-  },
+const yupResult = schemaToJsonSchema(yupSchema);
+console.log('Yup conversion:', yupResult);
+
+// ArkType schema (has built-in toJsonSchema)
+import { type } from 'arktype';
+const arkSchema = type({
+  name: 'string',
+  age: 'number',
 });
 
-// Example 4: Type-safe JSON Schema creation
-import { Type, Static } from '@sinclair/typebox';
+const arkResult = schemaToJsonSchema(arkSchema);
+console.log('ArkType conversion:', arkResult);
 
+// TypeBox (already JSON Schema)
+import { Type } from '@sinclair/typebox';
 const typeBoxSchema = Type.Object({
-  userId: Type.String(),
-  action: Type.Union([
-    Type.Literal('create'),
-    Type.Literal('update'),
-    Type.Literal('delete'),
-  ]),
-  timestamp: Type.Number(),
+  name: Type.String(),
+  age: Type.Number(),
 });
 
-type UserAction = Static<typeof typeBoxSchema>;
-
-export const processUserAction = task({
-  id: 'process-user-action',
-  // TypeBox schemas are already JSON Schema compliant
-  payloadSchema: typeBoxSchema,
-  run: async (payload) => {
-    // Cast to get type safety (or validate at runtime)
-    const action = payload as UserAction;
-    console.log(`User ${action.userId} performed ${action.action}`);
-    return { processed: true };
-  },
-});
+const typeBoxResult = schemaToJsonSchema(typeBoxSchema);
+console.log('TypeBox conversion:', typeBoxResult);
+
+// Example: Initialization (done automatically by the SDK)
+import { initializeSchemaConverters, areConvertersInitialized } from '@trigger.dev/schema-to-json';
+
+// The SDK calls this once when it loads
+await initializeSchemaConverters();
+
+// Check which converters are available
+const status = areConvertersInitialized();
+console.log('Converter status:', status);
+// { zod: true, yup: true, effect: true }
+
+// Example: How the SDK determines if a schema can be converted
+import { canConvertSchema, detectSchemaType } from '@trigger.dev/schema-to-json';
+
+const zodSchema = z.string();
+console.log('Can convert Zod?', canConvertSchema(zodSchema)); // true
+console.log('Schema type:', detectSchemaType(zodSchema)); // 'zod'
+
+// For users: Just use the SDK!
+// import { schemaTask } from '@trigger.dev/sdk/v3';
+// 
+// export const myTask = schemaTask({
+//   id: 'my-task',
+//   schema: zodSchema,
+//   run: async (payload) => { /* ... */ }
+// });

packages/schema-to-json/src/index.ts

@@ -1,9 +1,19 @@
-import type { JSONSchema7, JSONSchema7Definition } from '@types/json-schema';
+import type { JSONSchema7, JSONSchema7Definition, JSONSchema7Type, JSONSchema7TypeName, JSONSchema7Object, JSONSchema7Array } from '@types/json-schema';
 
 export type Schema = unknown;
 export type JSONSchema = JSONSchema7;
 export type JSONSchemaDefinition = JSONSchema7Definition;
 
+// Re-export the standard JSON Schema types for convenience
+export type {
+  JSONSchema7,
+  JSONSchema7Type,
+  JSONSchema7TypeName,
+  JSONSchema7Definition,
+  JSONSchema7Object,
+  JSONSchema7Array,
+} from '@types/json-schema';
+
 export interface ConversionOptions {
   /**
    * The name to use for the schema in the JSON Schema

packages/trigger-sdk/src/v3/index.ts

@@ -14,6 +14,7 @@ export * from "./timeout.js";
 export * from "./webhooks.js";
 export * from "./locals.js";
 export * from "./otel.js";
+export * from "./schemas.js";
 export type { Context };
 
 import type { Context } from "./shared.js";

packages/trigger-sdk/src/v3/schemas.ts

@@ -0,0 +1,12 @@
+// Re-export JSON Schema types for user convenience
+export type { JSONSchema, JSONSchemaDefinition } from "@trigger.dev/schema-to-json";
+
+// Re-export the standard JSON Schema types from @types/json-schema
+export type {
+  JSONSchema7,
+  JSONSchema7Type,
+  JSONSchema7TypeName,
+  JSONSchema7Definition,
+  JSONSchema7Object,
+  JSONSchema7Array,
+} from "@trigger.dev/schema-to-json";

packages/trigger-sdk/src/v3/shared.ts

@@ -28,10 +28,17 @@ import {
   TaskRunExecutionResult,
   TaskRunPromise,
 } from "@trigger.dev/core/v3";
-import { schemaToJsonSchema } from "@trigger.dev/schema-to-json";
+import { schemaToJsonSchema, initializeSchemaConverters } from "@trigger.dev/schema-to-json";
 import { PollOptions, runs } from "./runs.js";
 import { tracer } from "./tracer.js";
 
+// Initialize schema converters once when the module loads
+// This happens automatically, users don't need to know about it
+initializeSchemaConverters().catch(() => {
+  // Silently fail if converters can't be initialized
+  // Built-in conversions will still work
+});
+
 import type {
   AnyOnCatchErrorHookFunction,
   AnyOnCleanupHookFunction,

references/hello-world/package.json

@@ -8,7 +8,6 @@
   "dependencies": {
     "@trigger.dev/build": "workspace:*",
     "@trigger.dev/sdk": "workspace:*",
-    "@trigger.dev/schema-to-json": "workspace:*",
     "arktype": "^2.0.0",
     "openai": "^4.97.0",
     "puppeteer-core": "^24.15.0",

references/hello-world/src/trigger/jsonSchema.ts

@@ -1,14 +1,9 @@
-import { task, schemaTask, logger } from "@trigger.dev/sdk/v3";
+import { task, schemaTask, logger, type JSONSchema } from "@trigger.dev/sdk/v3";
 import { z } from "zod";
-import { schemaToJsonSchema, initializeSchemaConverters, type JSONSchema } from "@trigger.dev/schema-to-json";
 import * as y from "yup";
 import { type } from "arktype";
 import { Type, Static } from "@sinclair/typebox";
 
-// Initialize converters for schemas that need external libraries
-// This is only needed if you want to convert Zod 3, Yup, or Effect schemas
-await initializeSchemaConverters();
-
 // ===========================================
 // Example 1: Using schemaTask with Zod
 // ===========================================
@@ -235,8 +230,12 @@ export const processEventWithTypeBox = task({
 });
 
 // ===========================================
-// Example 6: Converting schemas at build time
+// Example 6: Using plain task with a Zod schema
 // ===========================================
+// If you need to use a plain task but have a Zod schema,
+// you should use schemaTask instead for better DX.
+// This example shows what NOT to do:
+
 const notificationSchema = z.object({
   recipientId: z.string(),
   type: z.enum(["email", "sms", "push"]),
@@ -247,17 +246,25 @@ const notificationSchema = z.object({
   metadata: z.record(z.unknown()).optional(),
 });
 
-// Convert the schema to JSON Schema at build time
-const notificationJsonSchema = schemaToJsonSchema(notificationSchema);
-
-export const sendNotificationWithConversion = task({
-  id: "json-schema-conversion-example",
-  // Use the converted JSON Schema
-  payloadSchema: notificationJsonSchema?.jsonSchema,
+// ❌ Don't do this - use schemaTask instead!
+export const sendNotificationBadExample = task({
+  id: "json-schema-dont-do-this",
   run: async (payload, { ctx }) => {
-    // Validate the payload using the original Zod schema
+    // You'd have to manually validate
     const notification = notificationSchema.parse(payload);
 
+    logger.info("This is not ideal - use schemaTask instead!");
+
+    return { sent: true };
+  },
+});
+
+// ✅ Do this instead - much better!
+export const sendNotificationGoodExample = schemaTask({
+  id: "json-schema-do-this-instead",
+  schema: notificationSchema,
+  run: async (notification, { ctx }) => {
+    // notification is already validated and typed!
     logger.info("Sending notification", { 
       recipientId: notification.recipientId,
       type: notification.type,