Binding reference Bindings

Use Vectorize when the worker really owns similarity search, not just string matching

Vectorize stores embeddings in Cloudflare-managed indexes for similarity search from Workers.

Devflare makes Vectorize usable by keeping the index name explicit in config, preview naming honest, and the real smoke test explicit instead of buried under mocks.

The right first path is small: one binding, one tiny upsert-and-query route, and one skip-aware remote smoke test that tells the truth about whether the real index was involved.

Config key
Authoring shape
Best for: Similarity search, embedding-backed lookup, and retrieval paths that belong in the worker

Add the binding to config

Vectorize authoring is simple in config, but the operational story matters: an index must exist, dimensions must match, and tests should acknowledge that they are calling a real remote system.

Devflare helps by keeping the binding explicit, the index name visible, and preview resource handling deliberate when the preview needs its own index.

Vectorize binding authoring

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'search-worker',

bindings: {

vectorize: {

DOCUMENT_INDEX: {

indexName: 'document-index'

}

})

Use the binding from application code

After Devflare generates the worker env, import from and keep the first Vectorize path close to the route, handler, or service method that needs it.

Keep this first path small enough that the config, env binding, and user-visible behavior are easy to review together.

A tiny write-and-query route

import { env } from 'devflare/runtime'

export async function fetch(): Promise<Response> {

const vector = Array(32).fill(0.5)

await env.DOCUMENT_INDEX.upsert?.([

{ id: 'doc-1', values: vector, metadata: { title: 'Demo doc' } }

])

const result = await env.DOCUMENT_INDEX.query?.(vector, {

topK: 1,

returnMetadata: true

})

return Response.json({ result })

}

Local and Remote Support

Devflare supports the config, generated env shape, docs, and local application-flow work, but full fidelity requires Cloudflare remote infrastructure. Use local shims or fixtures for code your app owns, then connect to Cloudflare when the product behavior is the assertion.

Remote-oriented; local tests require remote mode or explicit mocks. Keep local coverage focused on deterministic application flow through fixtures, mocks, shims, or Miniflare-backed wiring instead of pretending to reproduce Cloudflare-hosted product behavior.

Use Cloudflare when the index contract is business-critical enough to need explicit ci or release gating. This is the lane for full Vectorize product fidelity, remote state, lifecycle behavior, and platform-specific limits.

When this binding fits best

Use Vectorize when semantic similarity is part of the worker’s real job, not when plain text search is already enough.
It fits best when the worker is already producing or consuming embeddings as part of the application flow.
If the vector store is optional or external to the worker, keep the boundary explicit and do not force Vectorize into every local path.

Testing path

Real Vectorize tests need remote access and an index that actually exists.
Preview-scoped indexes are possible and lifecycle-managed, but they should be created only when the preview really needs isolated vector state.
Local fake vector stores can be useful above the worker boundary, but they are not proof that the real binding path works.

Dimension and index setup are part of the contract

A passing unit test with a fake array is not equivalent to a real Vectorize call against the configured index.

Open the next page when you need it

Subpage

Vectorize internals

Internals

Check emitted Wrangler , preview behavior, and Cloudflare-specific details.

Subpage

Testing Vectorize

Testing

Pick the in remote mode plus path first, then move to remote checks only when the test needs them.

Subpage

Vectorize example

Example

Copy a fuller application path when the quick example is too small.