tidewave 0.3.0 → 0.5.0

package/README.md

@@ -1,129 +1,222 @@
 # Tidewave
 
+> Tidewave Web for Next.js and React+Vite is currently in alpha testing!
+
 Tidewave is the coding agent for full-stack web app development.
 [See our website](https://tidewave.ai) for more information.
 
-Our current release connects your editor's assistant to your web framework
-runtime via [MCP](https://modelcontextprotocol.io/). Support for Tidewave Web
-will come in future releases.
+If you are using Next.js or you have a React + Vite frontend, talking either to
+a backend as a service (such as Supabase) or a third-party framework, you are in
+the right place!
 
-## Usage
+If you are using React with Django, FastAPI, Flask, Phoenix, or Rails,
+[follow the steps here instead](http://hexdocs.pm/tidewave/react.html).
 
-### Standalone MCP
+This project can also be used through the CLI or as a standalone Model Context
+Protocol (MCP) server for your editors.
 
-Tidewave's MCP server gives your editor and coding agents access to the
-documentation, type annotations, and source file locations of the packages being
-currently used by your project, without relying on external systems.
+## Installation
 
-Simply configure your editor to run `tidewave` in the same directory as your
-`package.json` as a STDIO MCP Server:
+### Next.js
 
-```bash
-npx tidewave mcp
-# or with Bun
-bunx tidewave mcp
-# or with Deno
-deno run npm:tidewave mcp
-```
+If you are using Next.js, install Tidewave with:
 
-Available MCP options:
-
-- `--prefix path` - Specify the directory to find the `package.json` file
-
-### HTTP MCP via Vite Plugin
+```sh
+$ npm install -D tidewave
+# or
+$ yarn add -D tidewave
+# or
+$ pnpm add --save-dev tidewave
+# or
+$ bun add --dev tidewave
+```
 
-Tidewave also provides HTTP-based MCP access through a Vite plugin for
-development environments. Add the plugin to your `vite.config.js`:
+Then create `pages/api/tidewave.ts` with:
 
-```javascript
-import { defineConfig } from 'vite';
-import tidewave from 'tidewave/vite-plugin';
+```typescript
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  if (process.env.NODE_ENV === 'development') {
+    const { tidewaveHandler } = await import('tidewave/next-js/handler');
+    const handler = await tidewaveHandler();
+    return handler(req, res);
+  } else {
+    res.status(404).end();
+  }
+}
 
-export default defineConfig({
-  plugins: [tidewave()],
-});
+export const config = {
+  runtime: 'nodejs',
+  api: {
+    bodyParser: false, // Tidewave already parses the body internally
+  },
+};
 ```
 
-This exposes MCP endpoints at `/tidewave/mcp` and `/tidewave/shell` during
-development.
+_Note: this uses the **Pages Router**, however it works regardless of the router
+type you use in your application._
 
-Configuration options:
+If you are using Next.js 16+, then create (or modify) `proxy.ts` with:
 
-```javascript
-tidewave({
-  allowRemoteAccess: false, // Allow access from remote IPs
-  allowedOrigins: ['localhost'], // Allowed origins: defaults to the Vite's host+port
-});
-```
-
-### HTTP MCP via Next.js Integration
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
 
-Tidewave provides seamless integration with Next.js through a handler function.
-Add the handler to your API routes **and** `middleware.ts`:
+export function proxy(req: NextRequest): NextResponse {
+  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL('/api/tidewave', req.url));
+  }
 
-> [!WARNING] Note that the below helper functions will only work on development
-> mode `NODE_ENV === 'development'` if the validation fails, an Error will be
-> thrown
+  // Here you could add your own logic or different middlewares.
+  return NextResponse.next();
+}
+```
 
-**Pages Router** - Create `pages/api/tidewave/[...all].ts`:
+For Next.js 15+ and earlier, create (or modify) `middleware.ts` with:
 
 ```typescript
-import { tidewaveHandler } from 'tidewave/next-js';
+import { NextRequest, NextResponse } from 'next/server';
 
-export default await tidewaveHandler();
+export function middleware(req: NextRequest): NextResponse {
+  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL('/api/tidewave', req.url));
+  }
+
+  // Here you could add your own logic or different middlewares.
+  return NextResponse.next();
+}
 
-// Next.js specific config
 export const config = {
-  runtime: 'nodejs',
-  api: {
-    bodyParser: false, // tidewave already parses the body internally
-  },
+  matcher: ['/tidewave/:path*'],
 };
 ```
 
-This exposes MCP endpoints at `/api/tidewave/mcp` and `/api/tidewave/shell`.
+Finally, we expose your application's spans, events, and logs to Tidewave MCP.
+First install the NodeSDK:
 
-Then create `middleware.ts` with:
+```sh
+npm install @opentelemetry/sdk-node
+```
+
+And then create (or modify) a custom `instrumentation.ts` file in the root
+directory of the project (or inside `src` folder if using one):
 
 ```typescript
-import { tidewaveMiddleware } from 'tidewave/next-js';
+// instrumentation.ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import type { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+
+export async function register() {
+  const runtime = process.env.NEXT_RUNTIME;
+  const env = process.env.NODE_ENV;
+
+  // Add your app own processes here existing configuration
+  const sdkConfig: {
+    spanProcessors: SpanProcessor[];
+    logRecordProcessors: LogRecordProcessor[];
+  } = {
+    spanProcessors: [],
+    logRecordProcessors: [],
+  };
+
+  // Conditionally add Tidewave processors in development
+  if (runtime === 'nodejs' && env === 'development') {
+    const { TidewaveSpanProcessor, TidewaveLogRecordProcessor } = await import(
+      'tidewave/next-js/instrumentation'
+    );
+
+    sdkConfig.spanProcessors.push(new TidewaveSpanProcessor());
+    sdkConfig.logRecordProcessors.push(new TidewaveLogRecordProcessor());
+  }
+
+  const sdk = new NodeSDK(sdkConfig);
+  sdk.start();
+}
+```
 
-export const middleware = tidewaveMiddleware();
+Now make sure
+[Tidewave is installed](https://hexdocs.pm/tidewave/installation.html) and you
+are ready to connect Tidewave to your app.
 
-export const config = {
-  matcher: '/tidewave/(.*)',
-};
+### React + Vite
+
+If you are building a front-end application, using a backend as a service, such
+as Supabase, or a non-officially supported web framework, we recommend using our
+React + Vite integration.
+
+Install it with:
+
+```sh
+$ npm install -D tidewave
+# or
+$ yarn add -D tidewave
+# or
+$ pnpm add --save-dev tidewave
+# or
+$ bun add --dev tidewave
 ```
 
-In case you already have an existing `middleware.ts`:
+Then configure your `vite.config.js` (also works for `.ts` and `.mjs`):
 
-```typescript
-import { tidewaveMiddleware } from 'tidewave/next-js';
-
-const withTidewave = tidewaveMiddleware();
-
-export function middleware(req: NextRequest): Promise<NextResponse> {
-  // This will return a unchanged NextResponse.next()
-  // if path doesn't match with `/tidewave`
-  // if does match it will rewrite to `/api/tidewave` instead
-  withTidewave(req, (req: NextRequest) => {
-    // your own logic
-    return NextResponse.json({ message: 'hello, world!' });
-  });
-}
+```javascript
+import { defineConfig } from 'vite';
+import tidewave from 'tidewave/vite-plugin';
 
-export const config = {
-  matcher: [
-    '/tidewave/(.*)', // tidewave specific matcher
-    '/your/route/', // your specific matcher
-  ],
-};
+export default defineConfig({
+  plugins: [tidewave()],
+});
+```
+
+Now make sure
+[Tidewave is installed](https://hexdocs.pm/tidewave/installation.html) and you
+are ready to connect Tidewave to your app.
+
+If you are using Supabase or similar, you can prompt Tidewave to use the
+`supabase` CLI so it has complete access to your database. For non-officially
+supported web frameworks, our React + Vite integration allows Tidewave Web to
+perform changes on the front-end, and the agent will be able to modify your
+backend code as usual, but some functionality (such as accessing logs, doing
+database calls, etc) won't be available.
+
+### Configuration
+
+Next.js' `tidewaveHandler` and Vite's `tidewave` accept the configuration
+options below:
+
+- `allow_remote_access:` allow remote connections when true (default false)
+- `allowed_origins:` defaults to the current host/port
+- `team`: enable Tidewave Web for teams
+
+## CLI
+
+Tidewave.js also comes with a CLI for developers who want to use it as a
+standalone MCP or query its functionality directly. Note this functionality is
+separate from Tidewave Web.
+
+### STDIO MCP
+
+Configure your editor to run `tidewave` in the same directory as your
+`package.json` as a STDIO MCP Server:
+
+```bash
+npx tidewave mcp
+# or with Bun
+bunx tidewave mcp
+# or with Deno
+deno run npm:tidewave mcp
 ```
 
-### CLI Usage
+Available options:
+
+- `--prefix path` - Specify the directory to find the `package.json` file
+
+### Get docs / get source
 
-Tidewave also provides the MCP features over a CLI tool. Use it directly via
-npx/bunx/deno:
+Fetch docs or retrieve the source location for classes, types, methods, etc:
 
 ```bash
 # Extract documentation for a symbol
@@ -149,14 +242,6 @@ npx tidewave source ./src/utils:formatDate
 npx tidewave source typescript:createProgram
 ```
 
-### Runtime Support
-
-Tidewave JavaScript supports multiple JavaScript runtimes:
-
-- **Node.js** - Full support with npm/npx
-- **Bun** - Native support with bunx
-- **Deno** - Support via npm: protocol
-
 ## Contributing
 
 ```bash