tidewave 0.2.4 → 0.4.0

package/README.md

@@ -1,39 +1,130 @@
 # Tidewave
 
+> Tidewave Web for Next.js 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.
+This package is recommended for JavaScript-powered backends as well as
+JavaScript libraries/applications using a backend as a service (such as
+Supabase). If you are using React with Phoenix, Rails, Django, or another
+server-side framework, [follow the steps here instead](http://hexdocs.pm/tidewave/react.html).
 
-## Usage
+This project can also be used as a standalone Model Context Protocol (MCP)
+server for your editors.
 
-### Standalone MCP
+## Installation
 
-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.
+### Next.js
 
-Simply configure your editor to run `tidewave` in the same directory as your
-`package.json` as a STDIO MCP Server:
+Install it with:
 
-```bash
-npx tidewave mcp
-# or with Bun
-bunx tidewave mcp
-# or with Deno
-deno run npm:tidewave mcp
+```sh
+$ npm install -D tidewave
+# or
+$ yarn add -D tidewave
+# or
+$ pnpm add --save-dev tidewave
+# or
+$ bun add --dev tidewave
 ```
 
-Available MCP options:
+Then create `pages/api/tidewave.ts` with:
+
+```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');
+    const handler = await tidewaveHandler();
+    return handler(req, res);
+  } else {
+    res.status(404).end();
+  }
+}
+
+export const config = {
+  runtime: 'nodejs',
+  api: {
+    bodyParser: false, // Tidewave already parses the body internally
+  },
+};
+```
 
-- `--prefix path` - Specify the directory to find the `package.json` file
+_Note: this uses the **Pages Router**, however it works regardless of the router
+type you use in your application._
+
+Then create (or modify) `middleware.ts` with:
 
-### HTTP MCP via Vite Plugin
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+
+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();
+}
+
+export const config = {
+  matcher: ['/tidewave/:path*'],
+};
+```
+
+Finally, we recommend creating the `instrumentation.ts` file below,
+to expose your application's spans, events, and logs to Tidewave/MCP:
+
+```typescript
+// instrumentation.ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+
+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: [],
+    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();
+}
+```
+
+### React + Vite
+
+Install it with:
+
+```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 configure your `vite.config.js` (also works for `.ts` and `.mjs`):
 
 ```javascript
 import { defineConfig } from 'vite';
@@ -44,22 +135,40 @@ export default defineConfig({
 });
 ```
 
-This exposes MCP endpoints at `/tidewave/mcp` and `/tidewave/shell` during
-development.
+### Configuration
 
-Configuration options:
+Next.js' `tidewaveHandler` and Vite's `tidewave` accept the configuration options below:
 
-```javascript
-tidewave({
-  allowRemoteAccess: false, // Allow access from remote IPs
-  allowedOrigins: ['localhost'], // Allowed origins: defaults to the Vite's host+port
-});
+- `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
@@ -85,14 +194,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