Skip to content

Commit 7714a40

Browse files
josevalimjosevalim
authored
Revise README for installation and usage clarity
Signed-off-by: José Valim <jose.valim@dashbit.co>
1 parent d965a2a commit 7714a40

1 file changed

Lines changed: 71 additions & 123 deletions

File tree

‎README.md‎

Lines changed: 71 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,21 @@
11
# Tidewave
22

3+
> Tidewave Web for Next.js is currently in alpha testing!
4+
35
Tidewave is the coding agent for full-stack web app development.
46
[See our website](https://tidewave.ai) for more information.
57

68
This package is recommended for JavaScript-powered backends as well as
7-
JavaScript libraries/applications without a backend. If you are using React with
8-
Phoenix, Rails, Django, or another server-side framework,
9-
[follow the steps here instead](http://hexdocs.pm/tidewave/react.html).
10-
11-
Our current release connects your editor's assistant to JavaScript runtime via
12-
[MCP](https://modelcontextprotocol.io/). Tidewave's MCP server gives your editor
13-
and coding agents access to the documentation, type annotations, and source file
14-
locations of the packages being currently used by your project, without relying
15-
on external systems.
16-
17-
Support for Tidewave Web will come in future releases.
18-
19-
## Usage
20-
21-
### Standalone MCP
22-
23-
Configure your editor to run `tidewave` in the same directory as your
24-
`package.json` as a STDIO MCP Server:
25-
26-
```bash
27-
npx tidewave mcp
28-
# or with Bun
29-
bunx tidewave mcp
30-
# or with Deno
31-
deno run npm:tidewave mcp
32-
```
33-
34-
Available MCP options:
35-
36-
- `--prefix path` - Specify the directory to find the `package.json` file
37-
38-
### HTTP MCP via Vite Plugin
39-
40-
Tidewave also provides HTTP-based MCP access through a Vite plugin for
41-
development environments. Add the plugin to your `vite.config.js`:
42-
43-
Install it with:
44-
45-
```sh
46-
$ npm install -D tidewave
47-
# or
48-
$ yarn add -D tidewave
49-
# or
50-
$ pnpm add --save-dev tidewave
51-
# or
52-
$ bun add --dev tidewave
53-
```
9+
JavaScript libraries/applications using a backend as a service (such as
10+
Supabase). If you are using React with Phoenix, Rails, Django, or another
11+
server-side framework, [follow the steps here instead](http://hexdocs.pm/tidewave/react.html).
5412

55-
Then, configure it:
13+
This project can also be used as a standalone Model Context Protocol (MCP)
14+
server for your editors.
5615

57-
```javascript
58-
import { defineConfig } from 'vite';
59-
import tidewave from 'tidewave/vite-plugin';
16+
## Installation
6017

61-
export default defineConfig({
62-
plugins: [tidewave()],
63-
});
64-
```
65-
66-
This exposes the MCP endpoint at `/tidewave/mcp`.
67-
68-
Configuration options:
69-
70-
```javascript
71-
tidewave({
72-
allowRemoteAccess: false, // Allow access from remote IPs
73-
allowedOrigins: ['localhost'], // Allowed origins: defaults to the Vite's host+port
74-
});
75-
```
76-
77-
### HTTP MCP for Next.js
78-
79-
Tidewave provides seamless integration with Next.js, you only need to expose its
80-
routes and then plug its middleware accordingly.
18+
### Next.js
8119

8220
Install it with:
8321

@@ -91,9 +29,7 @@ $ pnpm add --save-dev tidewave
9129
$ bun add --dev tidewave
9230
```
9331

94-
Then, configure it:
95-
96-
Create `pages/api/tidewave.ts` with:
32+
Then create `pages/api/tidewave.ts` with:
9733

9834
```typescript
9935
import type { NextApiRequest, NextApiResponse } from 'next';
@@ -141,48 +77,8 @@ export const config = {
14177
};
14278
```
14379

144-
This exposes the MCP endpoint at `/tidewave/mcp`.
145-
146-
**Logging** (optional): To capture application logs for debugging via the
147-
`get_logs` MCP tool, add OpenTelemetry instrumentation.
148-
149-
Create an `instrumentation.ts` file in your project root:
150-
151-
```typescript
152-
// instrumentation.ts
153-
import { NodeSDK } from '@opentelemetry/sdk-node';
154-
155-
export async function register() {
156-
const runtime = process.env.NEXT_RUNTIME;
157-
const env = process.env.NODE_ENV;
158-
159-
if (runtime === 'nodejs' && env === 'development') {
160-
const { TidewaveSpanProcessor, TidewaveLogRecordProcessor } = await import(
161-
'tidewave/next-js/instrumentation'
162-
);
163-
164-
const sdk = new NodeSDK({
165-
spanProcessors: [new TidewaveSpanProcessor()],
166-
logRecordProcessors: [new TidewaveLogRecordProcessor()], // Optional
167-
});
168-
169-
sdk.start();
170-
}
171-
}
172-
```
173-
174-
This captures:
175-
176-
- Console logs (`console.log`, `console.error`, etc.) - automatic when you
177-
import the module
178-
- Next.js HTTP request/response spans (`GET /api/users 200 45ms`) - via
179-
`TidewaveSpanProcessor`
180-
- OpenTelemetry logger logs - via `TidewaveLogRecordProcessor` (optional)
181-
182-
#### With Existing OpenTelemetry Setup
183-
184-
If you already have custom OpenTelemetry instrumentation, simply add the
185-
Tidewave processors to your existing setup:
80+
Finally, we recommend creating the `instrumentation.ts` file below,
81+
to expose your application's spans, events, and logs to Tidewave/MCP:
18682

18783
```typescript
18884
// instrumentation.ts
@@ -193,9 +89,9 @@ export async function register() {
19389
const runtime = process.env.NEXT_RUNTIME;
19490
const env = process.env.NODE_ENV;
19591

196-
// Your existing configuration
92+
// Add your app own processes here existing configuration
19793
const sdkConfig = {
198-
spanProcessors: [new BatchSpanProcessor(yourExporter)],
94+
spanProcessors: [],
19995
logRecordProcessors: [],
20096
};
20197

@@ -214,13 +110,65 @@ export async function register() {
214110
}
215111
```
216112

217-
This allows Tidewave to capture logs alongside your existing OpenTelemetry setup
218-
without conflicts.
113+
### React + Vite
114+
115+
Install it with:
116+
117+
```sh
118+
$ npm install -D tidewave
119+
# or
120+
$ yarn add -D tidewave
121+
# or
122+
$ pnpm add --save-dev tidewave
123+
# or
124+
$ bun add --dev tidewave
125+
```
126+
127+
Then configure your `vite.config.js` (also works for `.ts` and `.mjs`):
128+
129+
```javascript
130+
import { defineConfig } from 'vite';
131+
import tidewave from 'tidewave/vite-plugin';
132+
133+
export default defineConfig({
134+
plugins: [tidewave()],
135+
});
136+
```
137+
138+
### Configuration
139+
140+
Next.js' `tidewaveHandler` and Vite's `tidewave` accept the configuration options below:
141+
142+
- `allow_remote_access:` allow remote connections when true (default false)
143+
- `allowed_origins:` defaults to the current host/port
144+
- `team`: enable Tidewave Web for teams
145+
146+
## CLI
147+
148+
Tidewave.js also comes with a CLI for developers who want to use it
149+
as a standalone MCP or query its functionality directly. Note this
150+
functionality is separate from Tidewave Web.
151+
152+
### STDIO MCP
153+
154+
Configure your editor to run `tidewave` in the same directory as your
155+
`package.json` as a STDIO MCP Server:
156+
157+
```bash
158+
npx tidewave mcp
159+
# or with Bun
160+
bunx tidewave mcp
161+
# or with Deno
162+
deno run npm:tidewave mcp
163+
```
164+
165+
Available options:
166+
167+
- `--prefix path` - Specify the directory to find the `package.json` file
219168

220-
### CLI Usage
169+
### Get docs / get source
221170

222-
Tidewave also provides the MCP features over a CLI tool. Use it directly via
223-
npx/bunx/deno:
171+
Fetch docs or retrieve the source location for classes, types, methods, etc:
224172

225173
```bash
226174
# Extract documentation for a symbol

0 commit comments

Comments
 (0)