azure-search-openai-javascript: RAG on Azure with TypeScript

What This Sample Demonstrates

Retrieval Augmented Generation connects a language model to a private document corpus. Rather than relying on the model's training data, an RAG system retrieves relevant passages from a search index at query time and includes them in the prompt. The model then answers the question using those passages as context, which lets it cite specific documents and reduces hallucination on domain-specific topics.

This repository provides a complete, deployable TypeScript application demonstrating that pattern on Azure. It uses Azure AI Search as the retrieval layer and the gpt-4o-mini model from Azure OpenAI for response generation. The included sample data represents a fictitious company called Contoso Real Estate, covering terms of service, privacy policy, and a support guide. This lets a new engineer deploy the stack, ask questions, and see cited responses before connecting their own documents.

The repository targets TypeScript-fluent teams building internal enterprise chat tools on Azure. It is a sample application meant to be forked and modified, not a library.

Three-Service Architecture: Search, Indexer, and Web App

The application is structured as an npm workspace with three packages under `packages/`. The search service exposes the retrieval and response generation API. The indexer service preprocesses documents and populates the Azure AI Search index. The web application is the chat frontend that calls the search service and renders citations.

All three services start together with a single command from the workspace root:

npm start

The root `package.json` wires this to `concurrently "npm:start:*" --kill-others`, which starts all three `dev` scripts in parallel and stops all processes when any one exits. Node.js 22 or later and npm 10 or later are required, as declared in the `engines` field of `package.json`.

The separation between the indexer and search service matters for production: documents are indexed once (or on a schedule), while the search service handles live user queries. The indexer does not need to run continuously after the initial data load.

Azure Prerequisites and Deployment Path

Deploying this sample requires an Azure account, an Azure subscription with Azure OpenAI access enabled (which requires a separate access request via a Microsoft form), and an account with the `Microsoft.Authorization/roleAssignments/write` permission at the subscription level. Teams without subscription-level RBAC permissions can still deploy by targeting an existing resource group, but the account must have that permission scoped to the group.

The repository supports three setup paths. GitHub Codespaces provides a preconfigured browser-based VS Code environment. VS Code Remote Containers opens the project locally using the Dev Containers extension. Local setup follows standard steps.

Once the environment is ready, the Azure Developer CLI (`azd`) command handles provisioning and deployment. The README warns about ongoing costs from the provisioned resources: Azure Container Apps, Azure AI Search (Standard tier), Azure OpenAI, Azure Blob Storage, and optionally Azure Monitor. To remove all provisioned resources:

azd down --purge

The `--purge` flag permanently removes resources rather than soft-deleting them, which matters for Azure OpenAI quotas.

RAG Data Flow and Citation Handling

When a user submits a question, the web application sends it to the search service. The search service queries Azure AI Search, retrieves the most relevant document chunks, constructs a prompt combining the user question with those chunks, and sends the prompt to the gpt-4o-mini model via Azure OpenAI. The model's response includes citations that point back to the source documents.

The sample includes UX controls for experimenting with retrieval parameters, such as the number of retrieved documents and the prompt construction strategy. This lets engineers see how changing retrieval depth or prompt format affects answer quality without modifying code. The README describes this as a way to evaluate the trustworthiness of responses.

Optional Application Insights integration provides performance tracing and monitoring across the three services. The README notes this is disabled by default but can be enabled through deployment configuration.

Testing and Local Development

The monorepo includes Playwright end-to-end tests and k6 load tests. Running the Playwright tests requires the test environment to be installed separately:

npm run install:playwright

Unit and integration tests across all packages run with:

npm test

The project uses ESLint for linting and Prettier for formatting. A pre-commit hook runs `lint-staged` via `simple-git-hooks`. The Prettier configuration in the root `package.json` sets `tabWidth: 2`, `semi: true`, `singleQuote: true`, and `printWidth: 120`. Deviations from this format will fail the pre-commit hook.

The `.devcontainer/` directory provides a complete development environment specification that installs all required Azure CLI tools, Node.js, and extensions when the container starts. This is the fastest path to a working local environment without manual tool installation.

Limitations and Cost Considerations

The most significant constraint is the hard Azure dependency. Every component of the data layer, the model, and the indexing pipeline requires an active Azure subscription and billable services. The README explicitly states that exact costs cannot be estimated and points to the Azure pricing calculator for each service tier. Azure AI Search at the Standard tier, which this sample uses, incurs hourly charges even when idle.

The gpt-4o-mini model is billed per token, with a minimum of roughly 1,000 tokens consumed per question according to the cost section of the README. Long conversations or large document corpora increase costs significantly.

This sample covers only the Azure AI Search plus Azure OpenAI combination. Teams who want to use a different vector database or a different LLM provider would need to replace the search and indexer packages entirely. The README mentions a "using a different backend" guidance section but the full content was not available in the repository material reviewed.

Alternatives: LangChain.js RAG Reference and Self-Hosted Options

LangChain.js provides a JavaScript/TypeScript RAG framework that is not tied to Azure. Where azure-search-openai-javascript is a complete deployed application built on Azure-specific services, LangChain.js is a library of composable components (document loaders, text splitters, vector stores, chains) that works with many different providers including local models. Teams who need a cloud-agnostic solution, or who want to mix components from different providers, would start with LangChain.js instead.

The trade-off is setup time: LangChain.js requires assembling the components manually, while azure-search-openai-javascript provides a deployable application with a chat UI and citation rendering already built. For teams whose requirement is specifically to get a working Azure RAG chat interface running quickly, the sample offers a faster path than building from LangChain.js primitives. For teams that need flexibility or vendor independence, LangChain.js is the more practical foundation.

Editorial conclusion

This sample is the right starting point for teams already committed to Azure who want a working TypeScript RAG application they can modify, not a library or framework they install as a dependency. It is not appropriate for teams who want a cloud-agnostic solution, who lack an Azure subscription with OpenAI access enabled, or who need a self-hosted setup. Before deploying, verify that your Azure account has the Microsoft.Authorization/roleAssignments/write permission at the subscription level; the deployment will fail silently on RBAC errors without that role.

Frequently asked questions

Official sources

1. Azure-Samples/azure-search-openai-javascript on GitHub
2. Issues
3. License: MIT
4. README