Azure-Samples/azure-search-openai-javascript: a TypeScript RAG sample that deploys with azd

What azure-search-openai-javascript actually gives you

The repository is a sample, and the README says so plainly: it "demonstrates a few approaches for creating ChatGPT-like experiences over your own data using the Retrieval Augmented Generation pattern." The problem it addresses is the gap between a raw model and an answer you can trust. A language model alone has no access to your documents and no way to show where an answer came from. This sample closes that gap with retrieval: documents are indexed, a question triggers a search, and the retrieved passages are placed into the prompt before the model responds.

The audience is narrow and worth naming. You are on Azure, or willing to be. You want TypeScript, not Python. You are comfortable reading infrastructure-as-code and running a deployment that provisions real cloud resources. If you are looking for a library to import into an existing application, this is the wrong shape of thing. It is a complete application, split into services, with sample data about a fictitious company called Contoso Real Estate: documents covering its terms of service, privacy policy and a support guide. That data is what makes it runnable end to end on the first deploy.

The README lists the features as chat and Q&A interfaces, citations and source tracking to help users judge whether a response is trustworthy, settings in the UI for experimenting with options, and optional tracing through Application Insights. Those are the parts worth studying. The citations and the settings panel are where the sample does more than a minimal demo.

Three services, one deployment: the architecture in the repository

The README describes the application as made from multiple components. The search service is the backend that provides search and retrieval. The indexer service indexes the data and creates the search indexes. The web app is the frontend that provides the user interface and orchestrates the interaction between the user and the backend services. There is an architecture diagram at docs/app-architecture.drawio.png and a RAG diagram at docs/rag-architecture.png, both referenced from the README.

The data flow follows from that split. The indexer reads source documents, in this case the Contoso sample files under the data directory, and writes them into an Azure AI Search index. The search service answers retrieval requests against that index. The web app takes a user question, calls the search service, assembles a prompt from the retrieved content, and sends it to Azure OpenAI. LangChain appears in the project description as the layer used with the large language models, and the topics list includes langchain-js and langchain-typescript, so the orchestration is JavaScript-side rather than a service.

The repository layout confirms the split at the filesystem level. The packages directory holds the workspaces, and package.json declares "workspaces": ["packages/*"] with start scripts named start:webapp, start:search and start:indexer, each delegating to a workspace. The infra directory holds the deployment templates, and azure.yaml is the Azure Developer CLI project file. That is the mechanism that lets a single command provision the Azure resources and push the services. The root package.json is marked "private": true, which is consistent with an application rather than a published package.

Deploying it from scratch and asking the first question

The README directs you to three setup routes: GitHub Codespaces, VS Code Remote Containers, or a local environment. Codespaces is described as the easiest, with preconfiguration for all the tools. The prerequisites are not optional. You need an Azure account, a subscription with access enabled for Azure OpenAI, and an account holding Microsoft.Authorization/roleAssignments/write plus Microsoft.Resources/deployments/write at subscription level. Without the role assignment permission the deployment cannot create the identities it needs.

The local path starts from the repository root. The root package.json sets engines to node >=22 and npm >=10, so check those before anything else. Then install the workspace dependencies:

npm install

The Azure Developer CLI drives the deployment. The README covers deploying from scratch and deploying with existing resources as separate flows; the from-scratch command is the one to start with, and azure.yaml is the file azd reads to know what to provision and where the services live:

azd auth login
azd up

The README states that the sample data ships with the repo, so the indexer has something to work on and the app is usable after the first deployment. Once the web app is reachable, the first real use is the one the sample was built around: open the chat interface and ask a support question about the Contoso products. The README says the experience allows customers to ask support questions about the usage of its products. You should see an answer with citations back to the source documents, and the settings panel in the UI is where you change retrieval behavior to see how the answer moves. When you are finished, the README gives the teardown command and warns about leaving resources running:

azd down --purge

For development against a running environment, the root scripts run all three services together with concurrently and kill-others, which means stopping one stops the set. Running npm run start:indexer, npm run start:search and npm run start:webapp separately is the way to work on one service without the others restarting.

Where the sample stops being useful

The README has a productionizing section, and its existence is the honest signal. A sample that needs a section on how to make it production-ready is telling you it is not production-ready. Treat the deployed result as a reference implementation you will fork and change, not as something to point at customer traffic.

The cost model is the other constraint. The README says pricing may vary per region and usage and that exact costs cannot be estimated, then lists the resources involved. Azure AI Search is described as Standard tier with one replica and the free level of semantic search, priced per hour. Azure OpenAI is priced per 1K tokens, and the README notes at least 1K tokens are used per question. That means an idle deployment still bills for search capacity, and a busy one bills on both axes. The README also carries a caveat that the pricing may reflect an outdated tier model and points to the linked page for accuracy, which is a reasonable thing for a sample to say and a reason to check current pricing yourself.

There is a second failure mode that has nothing to do with code. Azure OpenAI access is gated. The README says your subscription must have access enabled and links a request form. If that request is not approved, the deployment cannot work regardless of how well you follow the rest of the instructions. Teams that already have an approved subscription will not notice this; teams that do not will hit it on the first azd up. The permission requirements are similarly unforgiving: subscription-level deployment write access is uncommon in organizations that restrict what developers can create.

How it differs from the Python RAG samples and from LangChain on its own

The closest alternative is the Python version of the same pattern, azure-search-openai-demo, which the Azure Samples organization maintains alongside this repository. The difference is not capability. Both index documents into Azure AI Search and both call Azure OpenAI. The difference is the runtime and the team that has to own it. This repository is TypeScript throughout, with npm workspaces, ESLint, Prettier and Playwright in the root package.json, and Node 22 as the floor. A JavaScript team can read every file in the stack without context switching. A Python team gains nothing from it and should use the Python sample, which has the larger ecosystem of adjacent tooling around document parsing and evaluation.

The second alternative is building directly on LangChain, which this sample already depends on. The distinction matters: LangChain gives you chains, retrievers and prompt templates as building blocks, but it does not give you an indexer, an Azure AI Search index schema, a web UI with citations, or a deployment template. Those are the parts of this repository that take time to get right, and they are the parts you would otherwise write yourself. Adopting LangChain alone is a smaller commitment and a larger amount of work.

The third comparison is to a managed retrieval product, where indexing and retrieval are someone else's operational problem. That trade is real but it is a different trade, and this repository does not make the case for or against it. What this sample offers instead is visibility: you can read the indexer code, the search service code and the prompt construction, and change any of them. That is the reason to pick it over a managed service, and the reason to avoid it if you would rather not operate search capacity at all.

Maintenance, upgrades and what the MIT licence covers

The repository is not archived, and the last push was on 2026-09-11. There are no releases retrieved for it, and the root package.json carries "version": "1.0.0" with "private": true, which is consistent with a sample that is tracked on the main branch rather than published and versioned. Practically, that means upgrades are not something you pull. You compare your fork against main and merge by hand, and you should expect the Azure Developer CLI templates under infra and azure.yaml to change as the underlying services change. The dependency surface is broad: Azure OpenAI, Azure AI Search, Azure Container Apps, Azure Static Web Apps, Azure Blob Storage and Azure Monitor all appear in the README's cost list, and each has its own API and pricing evolution.

The licence is MIT, declared in the root package.json and present as a LICENSE file at the top level. MIT is permissive: it allows commercial use, modification and redistribution, and it requires that the copyright notice and permission notice be included. It provides no warranty. That last part is the one to weigh, because this is sample code from a vendor. Nothing in the MIT grant obliges Microsoft to fix a bug you find or to keep the sample aligned with service changes. If you fork it into a product, you own the maintenance, and the AGENTS.md, CONTRIBUTING.md and SECURITY.md files at the top level describe the contribution and disclosure process for the repository itself, not a support contract for your deployment. This is a description of the licence terms, not legal advice; have your own counsel review anything you ship.

Editorial conclusion

Adopt this repo if you are building a chat or Q&A experience over your own documents on Azure and want a working TypeScript reference for the retrieval augmented generation pattern, including the indexer, the search backend and the web app. Do not adopt it if you need a supported product with a release cadence, or if you cannot get Azure OpenAI access and the RBAC permissions the README lists. Before deploying, confirm three things: that your subscription has Azure OpenAI enabled, that your account holds Microsoft.Authorization/roleAssignments/write and Microsoft.Resources/deployments/write, and that you have read the cost section, since the README states exact costs cannot be estimated and the Azure AI Search tier it describes is a Standard tier billed per hour.

Frequently asked questions

Official sources

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