tidewave 0.3.0 → 0.4.0

package/README.md

@@ -1,129 +1,174 @@
 # 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:
 
-- `--prefix path` - Specify the directory to find the `package.json` file
+```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();
+  }
+}
 
-### HTTP MCP via Vite Plugin
+export const config = {
+  runtime: 'nodejs',
+  api: {
+    bodyParser: false, // Tidewave already parses the body internally
+  },
+};
+```
 
-Tidewave also provides HTTP-based MCP access through a Vite plugin for
-development environments. Add the plugin to your `vite.config.js`:
+_Note: this uses the **Pages Router**, however it works regardless of the router
+type you use in your application._
 
-```javascript
-import { defineConfig } from 'vite';
-import tidewave from 'tidewave/vite-plugin';
+Then create (or modify) `middleware.ts` with:
 
-export default defineConfig({
-  plugins: [tidewave()],
-});
-```
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
 
-This exposes MCP endpoints at `/tidewave/mcp` and `/tidewave/shell` during
-development.
+export function middleware(req: NextRequest): NextResponse {
+  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL(`/api/tidewave`, req.url));
+  }
 
-Configuration options:
+  // Here you could add your own logic or different middlewares.
+  return NextResponse.next();
+}
 
-```javascript
-tidewave({
-  allowRemoteAccess: false, // Allow access from remote IPs
-  allowedOrigins: ['localhost'], // Allowed origins: defaults to the Vite's host+port
-});
+export const config = {
+  matcher: ['/tidewave/:path*'],
+};
 ```
 
-### HTTP MCP via Next.js Integration
+Finally, we recommend creating the `instrumentation.ts` file below,
+to expose your application's spans, events, and logs to Tidewave/MCP:
 
-Tidewave provides seamless integration with Next.js through a handler function.
-Add the handler to your API routes **and** `middleware.ts`:
+```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();
+}
+```
 
-> [!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
+### React + Vite
 
-**Pages Router** - Create `pages/api/tidewave/[...all].ts`:
+Install it with:
 
-```typescript
-import { tidewaveHandler } from 'tidewave/next-js';
+```sh
+$ npm install -D tidewave
+# or
+$ yarn add -D tidewave
+# or
+$ pnpm add --save-dev tidewave
+# or
+$ bun add --dev tidewave
+```
 
-export default await tidewaveHandler();
+Then configure your `vite.config.js` (also works for `.ts` and `.mjs`):
 
-// Next.js specific config
-export const config = {
-  runtime: 'nodejs',
-  api: {
-    bodyParser: false, // tidewave already parses the body internally
-  },
-};
+```javascript
+import { defineConfig } from 'vite';
+import tidewave from 'tidewave/vite-plugin';
+
+export default defineConfig({
+  plugins: [tidewave()],
+});
 ```
 
-This exposes MCP endpoints at `/api/tidewave/mcp` and `/api/tidewave/shell`.
+### Configuration
 
-Then create `middleware.ts` with:
+Next.js' `tidewaveHandler` and Vite's `tidewave` accept the configuration options below:
 
-```typescript
-import { tidewaveMiddleware } from 'tidewave/next-js';
+- `allow_remote_access:` allow remote connections when true (default false)
+- `allowed_origins:` defaults to the current host/port
+- `team`: enable Tidewave Web for teams
 
-export const middleware = tidewaveMiddleware();
+## CLI
 
-export const config = {
-  matcher: '/tidewave/(.*)',
-};
-```
+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.
 
-In case you already have an existing `middleware.ts`:
+### STDIO MCP
 
-```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!' });
-  });
-}
+Configure your editor to run `tidewave` in the same directory as your
+`package.json` as a STDIO MCP Server:
 
-export const config = {
-  matcher: [
-    '/tidewave/(.*)', // tidewave specific matcher
-    '/your/route/', // your specific matcher
-  ],
-};
+```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 +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