chore: remove Deno dependency and update flow compilation docs (#448)

# Remove Deno Dependency and Simplify Flow Compilation

This PR removes the Deno dependency requirement for pgflow and streamlines the flow compilation process:

- Removed Deno as a prerequisite in the CLI README
- Removed the deprecated `--deno-json` flag and related warning messages
- Added `--control-plane-url` option to the CLI for custom ControlPlane endpoints
- Updated documentation to reflect the HTTP-based compilation approach:
  - Removed the dedicated "Compile flow to SQL" page
  - Updated references to flow compilation throughout the docs
  - Added clarification that the ControlPlane is currently for local development only
  - Added notes that production deployments don't need the ControlPlane function yet
- Updated navigation links and redirects to point to the quickstart guide instead of the removed compilation page
- Enhanced troubleshooting sections with more specific guidance

These changes complete the transition to HTTP-based compilation introduced in v0.9.0, making pgflow easier to use by eliminating the local Deno dependency.

Author: jumski

pkgs/cli/README.md

@@ -16,7 +16,6 @@ This package provides essential tools for setting up, managing, and deploying pg
 ## Prerequisites
 
 - Supabase CLI v2.50.3 or higher
-- Deno v2.1.x or higher (for flow compilation)
 - Local Supabase project initialized
 
 ## Installation
@@ -70,8 +69,8 @@ npx pgflow@latest compile my_flow
 
 Options:
 
-- `--deno-json <path>` - Path to custom deno.json configuration file
 - `--supabase-path <path>` - Path to custom Supabase directory
+- `--control-plane-url <url>` - ControlPlane URL (default: `http://127.0.0.1:54321/functions/v1/pgflow`)
 
 The compiler will:
 

pkgs/cli/src/commands/compile/index.ts

@@ -98,23 +98,10 @@ export default (program: Command) => {
       new Option('--secret-key [key]', 'Supabase anon/service_role key')
         .hideHelp()
     )
-    .option(
-      '--deno-json <denoJsonPath>',
-      '[DEPRECATED] No longer used. Will be removed in v1.0'
-    )
     .action(async (flowSlug, options) => {
       intro('pgflow - Compile Flow to SQL');
 
       try {
-        // Show deprecation warning for --deno-json
-        if (options.denoJson) {
-          log.warn(
-            'The --deno-json flag is deprecated and no longer used.\n' +
-              'Flow compilation now happens via HTTP, not local Deno.\n' +
-              'This flag will be removed in v1.0'
-          );
-        }
-
         // Validate Supabase path
         let supabasePath: string;
         if (options.supabasePath) {

pkgs/website/astro.config.mjs

@@ -168,7 +168,6 @@ export default defineConfig({
             'get-started/installation',
             'get-started/flows/quickstart',
             'get-started/flows/create-flow',
-            'get-started/flows/compile-flow',
             'get-started/flows/run-flow',
             'concepts/how-pgflow-works',
             'concepts/data-model',

pkgs/website/redirects.config.mjs

@@ -49,7 +49,8 @@ export const redirects = {
   '/getting-started/': '/get-started/installation/',
   '/getting-started/install-pgflow/': '/get-started/installation/',
   '/getting-started/create-first-flow/': '/get-started/flows/create-flow/',
-  '/getting-started/compile-to-sql/': '/get-started/flows/compile-flow/',
+  '/getting-started/compile-to-sql/': '/get-started/flows/quickstart/',
+  '/get-started/flows/compile-flow/': '/get-started/flows/quickstart/',
   '/getting-started/run-flow/': '/get-started/flows/run-flow/',
   '/getting-started/configuration/': '/reference/configuration/',
   '/getting-started/update-pgflow/': '/deploy/update-pgflow/',

pkgs/website/src/components/PageFrame.astro

@@ -63,7 +63,7 @@ const showFooter = isLandingPage || isAuthorPage;
         <ul>
           <li><a href="/get-started/installation/">Installation</a></li>
           <li><a href="/get-started/flows/create-flow/">Create Flow</a></li>
-          <li><a href="/get-started/flows/compile-flow/">Compile Flow</a></li>
+          <li><a href="/get-started/flows/quickstart/">Quickstart</a></li>
           <li><a href="/get-started/flows/run-flow/">Run Flow</a></li>
           <li><a href="/project-status/">Project Status</a></li>
           <li><a href="/get-started/faq/">FAQ</a></li>

pkgs/website/src/content/docs/build/version-flows.mdx

@@ -68,7 +68,7 @@ Put the new flow in its own file with a versioned slug.
 
 2. **Compile it**
 
-   [Compile the new flow to SQL](/get-started/flows/compile-flow/) which generates a migration file:
+   Compile the new flow to SQL to generate a migration file:
 
    ```bash frame="none"
    npx pgflow@latest compile greetUserV2

pkgs/website/src/content/docs/concepts/compilation.mdx

@@ -67,6 +67,13 @@ This architecture provides several benefits:
 
 **Simpler CLI** - The CLI is a lightweight Node.js package that makes HTTP requests, rather than needing to bundle the entire compilation infrastructure.
 
+<Aside type="note" title="Production Deployment">
+The ControlPlane is currently used for local development compilation only.
+In future releases, it will be deployed to production for auto-compilation
+features where workers verify and compile flows at startup.
+For now, only deploy your worker functions to production.
+</Aside>
+
 ## Adding New Flows
 
 To make a flow available for compilation:

pkgs/website/src/content/docs/deploy/supabase/deploy-first-flow.mdx

@@ -19,6 +19,11 @@ Before deploying to production:
 - You have a Supabase project (free or paid tier)
 </Aside>
 
+<Aside type="note" title="ControlPlane Not Needed Yet">
+The `pgflow` ControlPlane function is for local compilation only.
+You do not need to deploy it to production yet - only deploy your worker functions.
+</Aside>
+
 ## Get Your Database Connection String
 
 Your workers need to connect to the production database:

pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx

@@ -119,6 +119,20 @@ Want to modify the flow structure? Flows are immutable once registered - this pr
 
 **In production:** Create a [versioned flow](/build/version-flows/) (e.g., `greetUserV2`) to preserve history.
 
+## Troubleshooting
+
+### "Could not connect to ControlPlane"
+
+Make sure edge functions are running:
+
+```bash frame="none"
+npx supabase functions serve --no-verify-jwt
+```
+
+### "Flow not found"
+
+Register your flow in `supabase/functions/pgflow/index.ts` and restart the functions server.
+
 ## Next steps
 
 <CardGrid>