[WIP] WIP address feedback on SvelteKit support implementation

.changeset/config.json

@@ -15,6 +15,7 @@
     "@workflow/example-hono",
     "@workflow/example-nitro-v3",
     "@workflow/example-nitro-v2",
-    "@workflow/example-nuxt"
+    "@workflow/example-nuxt",
+    "@workflow/example-sveltekit"
   ]
 }

.changeset/pre.json

@@ -26,7 +26,8 @@
     "nextjs-webpack": "0.0.2-alpha.5",
     "@workflow/example-nitro-v3": "0.0.0",
     "@workflow/example-nitro-v2": "0.0.0",
-    "@workflow/example-nuxt": "0.0.0"
+    "@workflow/example-nuxt": "0.0.0",
+    "@workflow/example-sveltekit": "0.0.0"
   },
   "changesets": [
     "angry-owls-beg",

.changeset/purple-regions-vanish.md

@@ -0,0 +1,9 @@
+---
+"@workflow/world-local": patch
+"@workflow/sveltekit": patch
+"workflow": patch
+"@workflow/core": patch
+"@workflow/cli": patch
+---
+
+Add sveltekit workflow integration

.github/workflows/tests.yml

@@ -56,6 +56,8 @@ jobs:
             project-id: "prj_avRPBF3eWjh6iDNQgmhH4VOg27h0"
           - name: "nitro"
             project-id: "prj_e7DZirYdLrQKXNrlxg7KmA6ABx8r"
+          - name: "sveltekit"
+            project-id: "prj_MqnBLm71ceXGSnm3Fs8i8gBnI23G"
     env:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
@@ -170,7 +172,7 @@ jobs:
         run: cd workbench/${{ matrix.app.name }} && ./resolve-symlinks.sh
 
       - name: Run E2E Tests (Next.js)
-        if: matrix.app.name != 'nitro'
+        if: matrix.app.name != 'nitro' && matrix.app.name != 'sveltekit'
         run: cd workbench/${{ matrix.app.name }} && pnpm dev & echo "starting tests in 10 seconds" && sleep 10 && pnpm vitest run packages/core/e2e/next-dev.test.ts && pnpm run test:e2e
         env:
           APP_NAME: ${{ matrix.app.name }}
@@ -182,6 +184,12 @@ jobs:
         env:
           APP_NAME: ${{ matrix.app.name }}
           DEPLOYMENT_URL: "http://localhost:3000"
+      - name: Run E2E Tests (SvelteKit)
+        if: matrix.app.name == 'sveltekit'
+        run: cd workbench/${{ matrix.app.name }} && pnpm dev & echo "starting tests in 10 seconds" && sleep 10 && pnpm vitest run packages/core/e2e/e2e.test.ts
+        env:
+          APP_NAME: ${{ matrix.app.name }}
+          DEPLOYMENT_URL: "http://localhost:3000"
 
   e2e-local-prod:
     name: E2E Local Prod Tests (${{ matrix.app.name }} - ${{ matrix.app.canary && 'canary' || 'stable' }})

docs/app/(home)/components/frameworks.tsx

@@ -485,11 +485,18 @@ export const Frameworks = () => {
           </Badge>
         </div>
 
-        <Link href="/docs/getting-started/next">
-          <Next className="size-[56px]" />
+        <Link href="/docs/getting-started/next" className="relative">
+          <Next className="size-[56px] relative" />
+          <Next className="size-[64px] absolute top-0 opacity-15 blur-lg -z-10" />
         </Link>
-        <Link href="/docs/getting-started/nitro">
+        <Link href="/docs/getting-started/nitro" className="relative">
           <Nitro className="size-[56px]" />
+          <Nitro className="size-[64px] absolute top-0 opacity-15 blur-lg -z-10" />
+        </Link>
+
+        <Link href="/docs/getting-started/sveltekit" className="relative">
+          <SvelteKit className="size-[56px]" />
+          <SvelteKit className="size-[64px] absolute top-0 opacity-15 blur-lg -z-10" />
         </Link>
 
         <div className="col-span-4 w-full pt-6">
@@ -508,13 +515,6 @@ export const Frameworks = () => {
             </span>
           </div>
         </div>
-        <div
-          className="group relative cursor-pointer size-[48px]"
-          onClick={() => handleRequest('SvelteKit')}
-        >
-          <SvelteKitGray className="size-[48px] opacity-70 transition-all duration-200 group-hover:opacity-0 group-hover:scale-95" />
-          <SvelteKit className="size-[48px] absolute inset-0 opacity-0 scale-95 transition-all duration-200 group-hover:opacity-100 group-hover:scale-100" />
-        </div>
         <div
           className="group relative cursor-pointer size-[60px]"
           onClick={() => handleRequest('Nuxt')}

docs/app/docs/[[...slug]]/page.tsx

@@ -34,7 +34,7 @@ function Card({ title, href, className, children, disabled }: CardProps) {
     <a
       href={href}
       className={cn(
-        'block rounded-lg border border-border p-6 transition hover:border-primary/25 hover:bg-accent no-underline duration-200',
+        'block rounded-lg border border-border p-6 transition hover:border-primary/25 hover:bg-accent no-underline duration-150 ease-out',
         className
       )}
     >

docs/content/docs/getting-started/index.mdx

@@ -25,10 +25,9 @@ Start by choosing your framework. Each guide will walk you through the steps to
         <Nitro className="size-16" />
         <span className="font-medium">Nitro</span>
     </Card>
-    <Card href="/docs/getting-started/sveltekit" disabled className="flex flex-col items-center justify-center text-center gap-2">
+    <Card href="/docs/getting-started/sveltekit" className="flex flex-col items-center justify-center text-center gap-2">
         <SvelteKit className="size-16" />
         <span className="font-medium">SvelteKit</span>
-        <Badge variant="secondary">Coming soon</Badge>
     </Card>
     <Card href="/docs/getting-started/nuxt" disabled className="flex flex-col items-center justify-center text-center gap-2">
         <Nuxt className="size-16" />

docs/content/docs/getting-started/sveltekit.mdx

@@ -0,0 +1,258 @@
+---
+title: SvelteKit
+---
+
+# SvelteKit
+
+This guide will walk through setting up your first workflow in a SvelteKit app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
+
+---
+
+<Steps>
+
+<Step>
+## Create Your SvelteKit Project
+
+Start by creating a new SvelteKit project. This command will create a new directory named `my-workflow-app` with a minimal setup and setup a SvelteKit project inside it.
+
+```bash
+npx sv create my-workflow-app --template=minimal --types=ts --no-add-ons
+```
+
+Enter the newly made directory:
+
+```bash
+cd my-workflow-app
+```
+
+### Install `workflow`
+
+<Tabs items={['npm', 'pnpm', 'yarn']}>
+  <Tab value="npm">
+    <CodeBlock>
+        npm i workflow
+    </CodeBlock>
+  </Tab>
+  <Tab value="pnpm">
+    <CodeBlock>
+        pnpm i workflow
+    </CodeBlock>
+  </Tab>
+  <Tab value="yarn">
+    <CodeBlock>
+        yarn add workflow
+    </CodeBlock>
+  </Tab>
+</Tabs>
+
+### Configure Vite
+
+Add `workflowPlugin()` to your Vite config. This enables usage of the `"use workflow"` and `"use step"` directives.
+
+```typescript title="vite.config.ts" lineNumbers
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+import { workflowPlugin } from "workflow/sveltekit"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [sveltekit(), workflowPlugin()], // [!code highlight]
+});
+```
+
+### Update `package.json`
+
+Update your `package.json` to include port `3000` for the development server:
+
+```json title="package.json" lineNumbers
+{
+  // ...
+  "scripts": {
+    "dev": "vite dev --port 3000"
+    // ...
+  },
+}
+```
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+    <AccordionTrigger className="text-sm">
+      ### Setup IntelliSense for TypeScript (Optional)
+    </AccordionTrigger>
+    <AccordionContent className="[&_p]:my-2">
+
+To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+
+```json title="tsconfig.json" lineNumbers
+{
+  "compilerOptions": {
+    // ... rest of your TypeScript config
+    "plugins": [
+      {
+        "name": "workflow" // [!code highlight]
+      }
+    ]
+  }
+}
+```
+
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+</Step>
+
+<Step>
+
+## Create Your First Workflow
+
+Create a new file for our first workflow:
+
+```typescript title="workflows/user-signup.ts" lineNumbers
+import { sleep } from "workflow";
+
+export async function handleUserSignup(email: string) {
+  "use workflow"; // [!code highlight]
+
+  const user = await createUser(email);
+  await sendWelcomeEmail(user);
+
+  await sleep("5s"); // Pause for 5s - doesn't consume any resources
+  await sendOnboardingEmail(user);
+
+  return { userId: user.id, status: "onboarded" };
+}
+
+```
+
+We'll fill in those functions next, but let's take a look at this code:
+
+* We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
+* The Workflow DevKit's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
+
+## Create Your Workflow Steps
+
+Let's now define those missing functions.
+
+```typescript title="workflows/user-signup.ts" lineNumbers
+import { FatalError } from "workflow"
+
+// Our workflow function defined earlier
+
+async function createUser(email: string) {
+  "use step"; // [!code highlight]
+
+  console.log(`Creating user with email: ${email}`);
+
+  // Full Node.js access - database calls, APIs, etc.
+  return { id: crypto.randomUUID(), email };
+}
+
+async function sendWelcomeEmail(user: { id: string; email: string; }) {
+  "use step"; // [!code highlight]
+
+  console.log(`Sending welcome email to user: ${user.id}`);
+
+  if (Math.random() < 0.3) {
+  // By default, steps will be retried for unhandled errors
+   throw new Error("Retryable!");
+  }
+}
+
+async function sendOnboardingEmail(user: { id: string; email: string}) {
+  "use step"; // [!code highlight]
+
+  if (!user.email.includes("@")) {
+    // To skip retrying, throw a FatalError instead
+    throw new FatalError("Invalid Email");
+  }
+
+  console.log(`Sending onboarding email to user: ${user.id}`);
+}
+```
+
+Taking a look at this code:
+
+* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
+* Steps can throw a `FatalError` if an error is intentional and should not be retried.
+
+<Callout>
+We'll dive deeper into workflows, steps, and other ways to suspend or handle events in [Foundations](/docs/foundations).
+</Callout>
+
+</Step>
+
+<Step>
+
+## Create Your Route Handler
+
+To invoke your new workflow, we'll have to add your workflow to a `POST` API route handler, `src/routes/api/signup/+server.ts` with the following code:
+
+```typescript title="src/routes/api/signup/+server.ts"
+import { start } from "workflow/api";
+import { handleUserSignup } from "../../../../workflows/user-signup";
+import { json, type RequestHandler } from "@sveltejs/kit";
+
+export const POST: RequestHandler = async ({
+  request,
+}: {
+  request: Request;
+}) => {
+  const { email } = await request.json();
+
+  // Executes asynchronously and doesn't block your app
+  await start(handleUserSignup, [email]);
+
+  return json({ message: "User signup workflow started" });
+};
+
+```
+
+This route handler creates a `POST` request endpoint at `/api/signup` that will trigger your workflow.
+
+<Callout>
+Workflows can be triggered from API routes or any server-side code.
+</Callout>
+
+</Step>
+
+</Steps>
+
+## Run in development
+
+To start your development server, run the following command in your terminal in the SvelteKit root directory:
+
+```bash
+npm run dev
+```
+
+Once your development server is running, you can trigger your workflow by running this command in the terminal:
+
+```bash
+curl -X POST --json '{"email":"[email protected]"}' http://localhost:3000/api/signup
+```
+
+Check the SvelteKit development server logs to see your workflow execute as well as the steps that are being processed.
+
+Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
+
+```bash
+npx workflow inspect runs
+# or add '--web' for an interactive Web based UI
+```
+
+<img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
+
+---
+
+## Deploying to production
+
+Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+
+Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
+
+## Next Steps
+
+* Learn more about the [Foundations](/docs/foundations).
+* Check [Errors](/docs/errors) if you encounter issues.
+* Explore the [API Reference](/docs/api-reference).