Installation
Install the alpha package, configure server-only credentials, and run on Node 24.
On this page
Requirements
- Use Node 24.22.1 or a newer patched Node 24 release. The SDK is ESM with TypeScript declarations and zero runtime dependencies.
- Use ESM imports in .mjs or a project with type: module; CommonJS callers can use dynamic import().
- The alpha channel is a prerelease; APIs may change before a stable release. Commit your package lockfile to retain the resolved version.
Install
# In your Node server application:
npm install @belweave/search-sdk@alphaFor a new application, run npm init --yes first. For TypeScript files run directly with Node 24, set type: module with npm pkg set type=module. The documented prerelease version is 0.1.0-alpha.0; the alpha tag selects the current prerelease.
Configure server credentials
Store provider keys in your application's server secret store or server environment. The SDK accepts keys explicitly; it does not load environment files or read environment variables itself.
const apiKey = process.env.CONTEXT_API_KEY;
if (!apiKey) throw new Error('CONTEXT_API_KEY is required');For local development, add .env to your server project's .gitignore, then put CONTEXT_API_KEY=your-provider-key in that local file. Run your server example with node --env-file=.env search.ts. Node loads the file; the SDK does not. In production, inject CONTEXT_API_KEY through your host's server secret configuration.
Do not prefix provider credentials with VITE_ or another public environment prefix. The hosted playground accepts request-scoped keys and calls providers from its server. The separate key-free demo uses fixtures. Call your own authenticated server route when building a browser application.
Choose the right import
| Import | Purpose |
|---|---|
@belweave/search-sdk | createSearch, SearchError, and public normalized types |
@belweave/search-sdk/context | Context.dev adapter and provider-specific exports |
@belweave/search-sdk/tinyfish | TinyFish adapter and provider-specific exports |
@belweave/search-sdk/testing | createMockProvider and fixture types |
Optional: build from source
Contributors and users testing an unreleased change can build a local tarball instead. Use the checkout's .nvmrc and locked dependencies. This command does not publish the package.
git clone https://github.com/Belweave/searchSDK.git
cd searchSDK
nvm use
npm ci
npm run build:sdk
npm pack -w @belweave/search-sdk
# In your server application, use the actual generated tarball:
npm install /absolute/path/belweave-search-sdk-0.1.0-alpha.0.tgz