--- title: Create a Coveo search interface project slug: q8qh2338 canonical_url: https://docs.coveo.com/en/q8qh2338/ collection: build-a-search-ui source_format: adoc --- # Create a Coveo search interface project This article explains how to scaffold a Coveo-powered search interface project with `npm create @coveo/ui`, the command-line tool that generates a project from Coveo's official samples. Use it to start a new Coveo Atomic or Coveo Headless implementation or to create a working reference project for experimentation. Generated projects run immediately against Coveo's public sample organization, so you don't need an organization ID, API key, or search token to see a working search or commerce interface. Once the project runs, you can point it at your own organization. > **Notes** > > * The command is `npm create @coveo/ui`, but the underlying npm package is named `@coveo/create-ui`. > This is standard npm behavior: `npm create /` resolves to the `/create-` package. > You never need to install the package yourself. > > * The `npm create @coveo/ui` command replaces the [Coveo CLI](https://docs.coveo.com/en/cli.md) scaffolding commands: `coveo ui:create:atomic`, `coveo ui:create:react`, `coveo ui:create:angular`, and `coveo ui:create:vue`. ## Prerequisites * Node.js 22.12 or later, or 24.11 or later. * npm or pnpm. The tool detects the package manager you use to run the command and uses it to install dependencies. ## Create a project [.float-group.list-float] -- ![Temp image](build-a-search-ui/animated-terminal-create-ui.gif) 1. In a terminal, navigate to the folder in which you want to create your project. 1. Run the following command: ```sh npm create @coveo/ui@latest ``` 1. When prompted, select the Coveo library and template you want to use, and then enter a project name. You can also skip the prompts by providing the project name and [template values](#available-interface-templates) directly: ```sh npm create @coveo/ui@latest my-new-app -- --template headless-search-react ``` The tool prompts only for omitted values. 1. Navigate to your new project folder. ```sh cd my-new-app ``` 1. Start your project. ```sh npm run dev ``` -- Your browser opens the new interface, which queries the Coveo sample organization. ## Command reference The following table lists the arguments and options available for `npm create @coveo/ui`. | Argument or option | Description | |---|---| | `` | Name of the project and the directory where it's created, resolved relative to the current directory. If you omit it, the tool prompts you for a name. | | `--template ` | Template to scaffold. If you omit it, the tool prompts you to select one. | | `--template-version ` | Version of the sample to scaffold, specified as a semantic version (for example, `3.53.2`) or an npm distribution tag (for example, `latest`). Samples are versioned in lockstep with the library they're built on, so this value specifies the Atomic or Headless version your project uses. Defaults to `latest`. | | `--docs` | Prints links to the Coveo documentation without scaffolding a project. | | `-h`, `--help` | Prints usage information, the full list of templates, and examples. | > **Note** > > Pin a version when you need to reproduce an issue with a specific library version. Otherwise, omit `--template-version` to use the latest sample. ## Available interface templates Each template is a Coveo-maintained sample published to npm. | `--template` value | Library | Use case | Framework | |---|---|---|---| | `atomic-search` | Atomic | Search | Vite | | `atomic-commerce` | Atomic | Commerce | Vite | | `atomic-search-react` | Atomic | Search | React | | `atomic-commerce-react` | Atomic | Commerce | React | | `headless-search` | Headless | Search | Vite | | `headless-commerce` | Headless | Commerce | Vite | | `headless-search-react` | Headless | Search | React | | `headless-commerce-react` | Headless | Commerce | React | | `headless-ssr-commerce-nextjs` | Headless SSR | Commerce | Next.js | | `headless-ssr-commerce-express` | Headless SSR | Commerce | Express | The template list evolves as Coveo publishes new samples. To see the templates currently available, run the following: ```sh npm create @coveo/ui@latest -- --help ``` ## Troubleshooting If project creation fails, review the error message and apply the corresponding solution that follows. **Unknown template ""**:: The template name is misspelled or doesn't exist. Run `npm create @coveo/ui@latest -- --help` to list the valid values. **Template "" version "" is not available**:: The requested version was never published for this sample, or it predates the version in which the sample first appeared. Omit `--template-version` to use the latest version. The tool doesn't scaffold a project when this error occurs. **Target directory "" already exists and is not empty**:: Use a different project name or empty the target directory. **Dependency installation failed**:: The project files were created, but dependencies weren't installed. Run `npm install` (or the equivalent command for your package manager) in the project folder. The tool also writes a local crash report if an unexpected failure occurs. You can submit the report using `npx @coveo/create-ui report `. Nothing is sent unless you submit the report. You can disable crash reporting by setting the `DO_NOT_TRACK` environment variable. ## Project metadata The tool writes a `.coveo/create-ui.json` file in your new project that records the template, sample version, tool version, creation date, `@coveo/*` dependency versions, and Node.js and package manager versions used. The file contains only tool non-sensitive metadata and remains in your project. If the tool can't write the file, the scaffolding process still succeeds, and the tool prints a warning. ## Connect your project to your own organization The generated project uses the Coveo sample organization, so you can start learning and prototyping immediately. To query your own content, replace the sample organization ID and access token in the project's Coveo configuration, as described in the [Coveo Atomic](https://docs.coveo.com/en/atomic/latest/) and [Coveo Headless](https://docs.coveo.com/en/headless/latest/) documentation. ## What's next? Customize the interface to meet your needs: * Add or update facets to filter on fields relevant to your use case. * Update result templates to display the information your users need. * Add components to leverage the full range of Coveo's relevance capabilities. For implementation guidance, see the documentation for your selected Coveo library: * [Coveo Atomic documentation](https://docs.coveo.com/en/atomic/latest/) * [Coveo Headless documentation](https://docs.coveo.com/en/headless/latest/)