Getting started
Before you begin, ensure you have the following installed on your system:
Node.js (v24 or higher) - Download from nodejs.org
npm (comes with Node.js) or yarn as your package manager
Git for version control
A Nosto account with Search and Categories enabled
Basic familiarity with Javascript/Typescript development
Installation
1. Clone the repository
First, clone the Search Templates Starter repository to your local machine. You can do this using the command line or via the GitHub UI:
Option 1: GitHub UI (Recommended)
Click the Use this template button to create your own repository, or click Code and select Download ZIP or Open with GitHub Desktop
If using the template feature, clone your new repository; if downloading, extract the ZIP file
Option 2: Command Line
git clone https://github.com/nosto/search-templates-starter.git
cd search-templates-starter2. Install dependencies
Install the required npm packages:
This will install all necessary dependencies for the project.
Configuration
Environment Setup
For local development, the Search Templates Starter requires your Nosto merchant ID to connect to your search data. This is not required for production builds. You can provide this in two ways:
Option 1: Environment File (Recommended) Create a .env file in the root of the project:
For Shopify merchants, you may also want to configure your store URL:
Option 2: Environment Variable
Finding your Merchant ID: You can find your merchant ID in the Nosto Admin UI under Account Settings, or it's typically in the format
platform-storeid(e.g.,shopify-12345678).
Development Configuration
The starter includes a configuration file at src/config.ts where you can customize:
CSS selectors for integration with your site — these define which DOM elements the search components are injected into via React Portals. They should match elements that exist on your store's search results page, category pages, and wherever your autocomplete input lives. If the selectors don't match anything on the page, the components won't appear.
Search behavior and settings
Component rendering options
Customized queries for SERP, category pages, and autocomplete
Connecting to Nosto CLI
Before you can push templates to your store, authenticate with the Nosto CLI:
This opens a browser window. If you already have a valid Nosto session, you are logged in automatically for the rest of the working day. Once authenticated, configure the CLI for your merchant:
This creates a .nosto.json configuration file in your project root. See Nosto CLI for full details on the CLI workflow.
Local Development
Development approaches
There are two ways to develop with Search Templates Starter. Choose based on what you need at a given moment — most developers use both during a project.
npm run dev — Vite dev server
Starts a local Vite dev server at http://localhost:8000. The page is a small mock store that mounts your components with your real Nosto data, but without your shop's styles or layout. Changes are reflected instantly in the browser via hot reload. This is the fastest way to work on component logic and appearance.
nosto st dev — watch mode on your real store
Watches your files, rebuilds on save, and pushes the artifacts to Nosto's infrastructure. Your changes become available in preview mode on your actual store — visit it with ?nostodebug=true and enable Preview in the debug toolbar, then refresh the page to see the update. This shows the templates exactly as they will appear when deployed, injected into your real store's pages.
Note:
nosto st devpushes to a shared S3 bucket tied to the merchant account. If multiple developers run it simultaneously against the same merchant, they will overwrite each other's uploads. Coordinate with your team to avoid conflicts — or usenpm run devfor local iteration and only switch tonosto st devwhen you need to verify on the real store.
Use npm run dev when iterating quickly on components. Use nosto st dev when you want to verify the result in context — with your real theme, real CSS, and real page structure.
Understanding Modes
Search Templates Starter may operate in three modes: Injected, Native and Mocked. For a typical store setup, you will most likely be using the Injected mode, as it is designed to integrate with any store page. Native mode is useful if you want to develop your store from the ground up using Search Templates Starter, and Mocked is primarily used for development and Storybook.
Injected Mode (Default)
In this mode, the components are rendered into the page using React Portals, targeting the elements you define with CSS selectors in src/config.ts. Note that without correct selectors, the components will not appear in the page at all. After the injection step, the rest of the application behaves nearly the same as it would in native mode.
Entry point:
src/entries/injected.tsx
Configure CSS selectors in src/config.ts to match your store's elements. To test the injected result on your actual store, use nosto st dev instead of the Vite dev server.
Native Mode
In this mode, the Starter behaves like a standard React/Preact app but still uses React Portals with a single injection point (#app). It creates the component tree and renders both search and results components together based on the page type (search results or category page). This is useful for:
Developing your store from the ground up using Search Templates Starter
Testing search functionality without existing page constraints
Rapid prototyping of new features
Entry point:
src/entries/native.tsx
Mocked Mode
Used automatically in Storybook and testing environments where components render with mock data for consistent development and testing.
Development Tools
Storybook for Component Development
Storybook is a powerful tool for developing, testing, and documenting UI components in isolation. It's a workbench for your components, allowing you to work on them without needing to run the entire application.
To start Storybook, run:
This opens Storybook in your browser, where you can explore the component library.
Why Use Storybook?
Focused Development: Concentrate on one component at a time.
Visual Testing: See how components look with different properties and states.
Rapid Prototyping: Quickly build and iterate on new components.
Component Library: Storybook acts as living documentation for your UI.
No merchant ID is required for Storybook, as all components are displayed with mock data.
AI and LLM Assistant Usage
Storybook is also a key tool for AI and LLM assistants. It allows automated agents to:
Visually test components they create or modify.
Understand the available components and their props.
Work on UI tasks in a simplified, sandboxed environment.
Essential Development Commands
Here are the key commands for your development workflow:
Testing
Code Quality
Building
Next Steps
Once you have the development environment running, you can:
Use the Nosto CLI - See Nosto CLI for deployment workflows
Leverage AI assistance - See LLM Examples for development productivity tips
Troubleshooting
Common Issues
Port already in use: If port 8000 is already in use, Vite will automatically try the next available port. You can also specify a custom port:
Missing merchant ID: Ensure your VITE_MERCHANT_ID environment variable is set correctly. The application cannot connect to Nosto's search API without it.
Build errors: Run npm run typecheck to identify TypeScript errors that might be causing build issues.
Last updated
Was this helpful?