From ed8abfb2103cd73417d2c8f5b89ba554819ad94c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 14:43:49 +0200 Subject: [PATCH 1/9] docs: starter docs --- .../implement-search-using-starter/README.md | 23 +++++++ .../getting-started.md | 66 +++++++++++++++++++ .../llm-examples.md | 13 ++++ .../nosto-cli.md | 51 ++++++++++++++ .../project-structure.md | 28 ++++++++ 5 files changed, 181 insertions(+) create mode 100644 implementing-nosto/implement-search/implement-search-using-starter/README.md create mode 100644 implementing-nosto/implement-search/implement-search-using-starter/getting-started.md create mode 100644 implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md create mode 100644 implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md create mode 100644 implementing-nosto/implement-search/implement-search-using-starter/project-structure.md diff --git a/implementing-nosto/implement-search/implement-search-using-starter/README.md b/implementing-nosto/implement-search/implement-search-using-starter/README.md new file mode 100644 index 0000000..49fcd77 --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/README.md @@ -0,0 +1,23 @@ +# Implement Search using Search Templates Starter + +This document provides a comprehensive overview of the Search Templates Starter, a Preact-based starter template for building ecommerce search experiences with Nosto. + +## What is Search Templates Starter? + +The Search Templates Starter is a foundational template for building Nosto search integrations. It utilizes `@nosto/search-js`, `@nosto/nosto-js` and Preact to provide a pre-configured environment with components, styles, and utilities to accelerate the development of search experiences on the Nosto platform. It is designed to be cloned, customized, and built upon to match your store's specific needs and branding. + +## Why is it used? + +Using the Search Templates Starter offers several advantages: + +- **Rapid Development:** Kickstart your project with a ready-to-use structure, saving time on setup and configuration. +- **Best Practices:** The template incorporates best practices for building search interfaces with Nosto's technology. +- **Customizable:** While it provides a solid foundation, every aspect of the template is designed to be customized and extended. +- **Integrated Tooling:** Comes with Vite for building, Storybook for component development, and Vitest for testing, providing a modern and efficient development workflow. + +## Table of Contents + +- [Getting Started](./getting-started.md) +- [Project Structure](./project-structure.md) +- [Utilizing LLMs for Development](./llm-examples.md) +- [Using the Nosto CLI](./nosto-cli.md) \ No newline at end of file diff --git a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md new file mode 100644 index 0000000..3097034 --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -0,0 +1,66 @@ +# Getting Started + +This guide will walk you through setting up and running the Search Templates Starter project on your local machine for development. + +## Prerequisites + +Ensure you have the following installed on your system: + +- Node.js (v22 or higher) +- npm + +## Installation + +1. **Clone the repository:** + + ```sh + git clone https://github.com/nosto/search-templates-starter.git + cd search-templates-starter + ``` + +2. **Install dependencies:** + + ```sh + npm install + ``` + +## Local Development + +To start the local development server, run the following command: + +```bash +VITE_MERCHANT_ID=your-merchant-id npm run dev +``` + +This will launch the application at `http://localhost:8000`. You can also provide the merchant ID via a `.env` file in the root of the project: + +``` +VITE_MERCHANT_ID=your-merchant-id +``` + +### Development Modes + +The starter template can run in three different modes: + +- **Native Mode:** In this mode, the application renders as a standard Preact app. This is useful for developing components in isolation. Use `npm run dev:native` to run in this mode. +- **Injected Mode:** This mode injects the search components into a live site using React Portals. You must configure the CSS selectors in `src/config.ts` to match the target elements on your page. +- **Mocked Mode:** This mode is used for Storybook and testing, where components are rendered with mock data. + +### Storybook + +To work on components in isolation, you can use Storybook: + +```sh +npm run storybook +``` + +This will open Storybook in your browser, where you can view and interact with all the available components. + +### Useful Development Commands + +Here are some other useful commands for local development: + +- `npm run test`: Run unit and integration tests with Vitest. +- `npm run test:e2e`: Run end-to-end tests with Playwright. +- `npm run lint`: Check the code for linting errors. +- `npm run typecheck`: Check for TypeScript errors. diff --git a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md new file mode 100644 index 0000000..737ced6 --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md @@ -0,0 +1,13 @@ +# Utilizing LLMs for Development + +Large Language Models (LLMs) can be powerful tools for accelerating development. Here are a few example prompts you can use to perform common tasks on this starter template: + +## Example: Migrating to Tailwind CSS + +**Prompt:** +> "Replace the existing CSS module structure with a single-tree Tailwind CSS setup. Migrate existing styling from CSS modules to Tailwind utility classes and remove the original CSS module files." + +## Example: Adding a new component + +**Prompt:** +> "Create a new `QuickView` component that shows product details in a modal when a button is clicked. The component should be placed in `src/components/QuickView`, and should include a Storybook story file. The modal should be built using the existing `Portal` element." diff --git a/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md b/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md new file mode 100644 index 0000000..9d93f13 --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md @@ -0,0 +1,51 @@ +# Using the Nosto CLI + +The [Nosto CLI](https://github.com/Nosto/nosto-cli) is a powerful command-line tool that allows you to develop and deploy your search templates directly to your Nosto account. This guide covers the essential commands for running the Search Templates Starter with the Nosto CLI. + +## Installation + +The Nosto CLI is already included as a dependency in this project, so you can run it using `npx nosto`. + +Alternatively, you can install it globally: + +```sh +npm install -g @nosto/nosto-cli +``` + +## Deployment Workflow + +Using the Nosto CLI, you can deploy the template straight to your store in a preview mode. Any changes you make will only be visible with the Nosto Debug Toolbar and preview mode enabled on your site. + +### 1. Login to Nosto + +First, you need to authenticate with your Nosto account. + +```bash +npx nosto login +``` + +This command will open a browser window for you to complete the login process. + +### 2. Setup the Project + +Next, create a configuration file for your project. This links your local repository to a specific Nosto merchant account. + +```bash +npx nosto setup -m YOUR_MERCHANT_ID +``` + +Replace `YOUR_MERCHANT_ID` with your actual Nosto account ID. + +### 3. Run in Development Mode + +To see your changes live on your site, run the `dev` command: + +```bash +npx nosto st dev +``` + +While this command is running, any changes you save to your local files will be automatically uploaded as a preview. You can see the changes by refreshing your store page with the Nosto Debug Toolbar enabled and "Preview" mode toggled on. + +### 4. Production Deployments + +Once you are happy with your changes in preview mode, you can create a production deployment from the Nosto Admin UI. Navigate to the Search Templates page, and you will be able to promote your latest preview to production. diff --git a/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md new file mode 100644 index 0000000..658b329 --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md @@ -0,0 +1,28 @@ +# Project Structure + +The Search Templates Starter is organized to promote scalability and maintainability. + +``` +/ +├── src/ +│ ├── components/ # Reusable Preact components +│ ├── contexts/ # React contexts for state management +│ ├── elements/ # Atomic UI elements +│ ├── entries/ # Entry points for different modes (native, injected) +│ ├── hooks/ # Custom hooks +│ ├── mapping/ # Data mapping and transformation logic +│ ├── plugins/ # Vite plugins +│ └── utils/ # Utility functions +├── test/ # Test files +│ └── e2e/ # End-to-end tests +├── mocks/ # Mock data for development and testing +├── docs/ # Documentation +└── ... # Configuration files +``` + +## Pros of this structure: + +- **Modularity:** Components are broken down into small, reusable pieces, making them easy to manage and test. +- **Separation of Concerns:** The structure separates components, business logic, and configuration, making the codebase easier to understand and navigate. +- **Scalability:** The organization is designed to scale with your project, allowing you to add new features and components without cluttering the codebase. +- **Testability:** With dedicated directories for tests and mocks, writing and running tests is straightforward. From f831fb55b097ab2682cfe87cb882afdfbd074c45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 15:08:29 +0200 Subject: [PATCH 2/9] docs: updates --- .../implement-search-using-starter/README.md | 42 ++- .../getting-started.md | 184 +++++++++++-- .../llm-examples.md | 259 +++++++++++++++++- .../nosto-cli.md | 197 +++++++++++-- .../project-structure.md | 198 +++++++++++-- 5 files changed, 790 insertions(+), 90 deletions(-) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/README.md b/implementing-nosto/implement-search/implement-search-using-starter/README.md index 49fcd77..1b11082 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/README.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/README.md @@ -1,23 +1,37 @@ # Implement Search using Search Templates Starter -This document provides a comprehensive overview of the Search Templates Starter, a Preact-based starter template for building ecommerce search experiences with Nosto. +The Search Templates Starter is a Preact-based starter template that provides a complete development environment for building custom search experiences with Nosto. -## What is Search Templates Starter? +## Why use Search Templates Starter? -The Search Templates Starter is a foundational template for building Nosto search integrations. It utilizes `@nosto/search-js`, `@nosto/nosto-js` and Preact to provide a pre-configured environment with components, styles, and utilities to accelerate the development of search experiences on the Nosto platform. It is designed to be cloned, customized, and built upon to match your store's specific needs and branding. +Search Templates Starter allows you to build fully custom search implementations with modern development practices. You get: -## Why is it used? +- **Full source code control** with Git version management +- **Modern development tooling** including TypeScript, Vitest, and Storybook +- **Local development environment** with hot reloading and debugging +- **Component library** with pre-built, customizable search components +- **Complete flexibility** to modify any aspect of the search experience -Using the Search Templates Starter offers several advantages: +This approach is ideal when you need advanced customization or when your development team prefers working with familiar local tools and workflows. -- **Rapid Development:** Kickstart your project with a ready-to-use structure, saving time on setup and configuration. -- **Best Practices:** The template incorporates best practices for building search interfaces with Nosto's technology. -- **Customizable:** While it provides a solid foundation, every aspect of the template is designed to be customized and extended. -- **Integrated Tooling:** Comes with Vite for building, Storybook for component development, and Vitest for testing, providing a modern and efficient development workflow. +## Get Started -## Table of Contents +To start developing with Search Templates Starter, you'll need Node.js 16+ and familiarity with React/Preact. -- [Getting Started](./getting-started.md) -- [Project Structure](./project-structure.md) -- [Utilizing LLMs for Development](./llm-examples.md) -- [Using the Nosto CLI](./nosto-cli.md) \ No newline at end of file +{% content-ref url="getting-started.md" %} +[getting-started.md](getting-started.md) +{% endcontent-ref %} + +## Implementation guides + +{% content-ref url="project-structure.md" %} +[project-structure.md](project-structure.md) +{% endcontent-ref %} + +{% content-ref url="llm-examples.md" %} +[llm-examples.md](llm-examples.md) +{% endcontent-ref %} + +{% content-ref url="nosto-cli.md" %} +[nosto-cli.md](nosto-cli.md) +{% endcontent-ref %} \ No newline at end of file diff --git a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md index 3097034..1ab2e0c 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -2,65 +2,189 @@ This guide will walk you through setting up and running the Search Templates Starter project on your local machine for development. +## Why use the Search Templates Starter? + +The Search Templates Starter provides a complete development environment for building custom search experiences with modern tools and practices. It's designed for developers who need: + +- **Full control** over the search implementation and codebase +- **Modern development workflow** with TypeScript, testing, and component development +- **Local development environment** that integrates with your existing tools and processes +- **Version control** and collaborative development capabilities + ## Prerequisites -Ensure you have the following installed on your system: +Before you begin, ensure you have the following installed on your system: -- Node.js (v22 or higher) -- npm +- **Node.js** (v22 or higher) - [Download from nodejs.org](https://nodejs.org/) +- **npm** (comes with Node.js) or **yarn** as your package manager +- **Git** for version control +- A **Nosto account** with Search module enabled +- Basic familiarity with **React/Preact** and modern JavaScript development ## Installation -1. **Clone the repository:** +### 1. Clone the repository - ```sh - git clone https://github.com/nosto/search-templates-starter.git - cd search-templates-starter - ``` +First, clone the Search Templates Starter repository to your local machine: -2. **Install dependencies:** +```sh +git clone https://github.com/nosto/search-templates-starter.git +cd search-templates-starter +``` - ```sh - npm install - ``` +### 2. Install dependencies -## Local Development +Install the required npm packages: + +```sh +npm install +``` + +This will install all necessary dependencies including: +- Preact for the UI framework +- Vite for build tooling and development server +- TypeScript for type safety +- Vitest for testing +- Storybook for component development + +## Configuration -To start the local development server, run the following command: +### Environment Setup +The Search Templates Starter requires your Nosto merchant ID to connect to your search data. You can provide this in two ways: + +**Option 1: Environment Variable** ```bash VITE_MERCHANT_ID=your-merchant-id npm run dev ``` -This will launch the application at `http://localhost:8000`. You can also provide the merchant ID via a `.env` file in the root of the project: - +**Option 2: Environment File** +Create a `.env` file in the root of the project: ``` VITE_MERCHANT_ID=your-merchant-id ``` -### Development Modes +> **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 +- Search behavior and settings +- Component rendering options + +## Local Development + +### Starting the Development Server + +To start the local development server: + +```bash +npm run dev +``` + +This will launch the application at `http://localhost:8000` with hot reloading enabled. Any changes you make to the source code will be automatically reflected in the browser. -The starter template can run in three different modes: +### Understanding Development Modes -- **Native Mode:** In this mode, the application renders as a standard Preact app. This is useful for developing components in isolation. Use `npm run dev:native` to run in this mode. -- **Injected Mode:** This mode injects the search components into a live site using React Portals. You must configure the CSS selectors in `src/config.ts` to match the target elements on your page. -- **Mocked Mode:** This mode is used for Storybook and testing, where components are rendered with mock data. +The Search Templates Starter supports multiple development modes to accommodate different workflows: -### Storybook +#### Native Mode +```bash +npm run dev:native +``` +In this mode, the application renders as a standalone Preact app. This is useful for: +- Developing components in isolation +- Testing search functionality without a live site +- Rapid prototyping of new features + +#### Injected Mode +```bash +npm run dev +``` +This is the default mode where search components are injected into a live site using React Portals. To use this mode effectively: +1. Configure CSS selectors in `src/config.ts` to match your site's elements +2. Ensure your site is accessible for injection +3. Test on your actual store to see real integration -To work on components in isolation, you can use Storybook: +#### 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 provides an isolated environment for developing and testing individual components: ```sh npm run storybook ``` -This will open Storybook in your browser, where you can view and interact with all the available components. +This opens Storybook in your browser where you can: +- View all available components +- Test different component states and props +- Develop components without needing a full application context +- Create and maintain component documentation + +### Essential Development Commands + +Here are the key commands for your development workflow: + +#### Testing +```bash +# Run unit and integration tests +npm run test + +# Run tests in watch mode during development +npm run test:watch + +# Run end-to-end tests with Playwright +npm run test:e2e +``` + +#### Code Quality +```bash +# Check for linting errors and style issues +npm run lint + +# Automatically fix linting issues where possible +npm run lint:fix + +# Check for TypeScript compilation errors +npm run typecheck +``` + +#### Building +```bash +# Create a production build +npm run build + +# Preview the production build locally +npm run preview +``` + +## Next Steps + +Once you have the development environment running, you can: + +1. **Explore the project structure** - See [Project Structure](project-structure.md) for detailed information +2. **Use the Nosto CLI** - See [Using the Nosto CLI](nosto-cli.md) for deployment workflows +3. **Leverage AI assistance** - See [LLM Examples](llm-examples.md) 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: +```bash +npm run dev -- --port 3000 +``` -### Useful Development Commands +**Missing merchant ID:** +Ensure your `VITE_MERCHANT_ID` environment variable is set correctly. The application cannot connect to Nosto's search API without it. -Here are some other useful commands for local development: +**Build errors:** +Run `npm run typecheck` to identify TypeScript errors that might be causing build issues. -- `npm run test`: Run unit and integration tests with Vitest. -- `npm run test:e2e`: Run end-to-end tests with Playwright. -- `npm run lint`: Check the code for linting errors. -- `npm run typecheck`: Check for TypeScript errors. +For additional support, refer to the [Nosto documentation](https://docs.nosto.com/) or contact Nosto support. diff --git a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md index 737ced6..c653d92 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md @@ -1,13 +1,258 @@ # Utilizing LLMs for Development -Large Language Models (LLMs) can be powerful tools for accelerating development. Here are a few example prompts you can use to perform common tasks on this starter template: +Large Language Models (LLMs) like GitHub Copilot, ChatGPT, and Claude can significantly accelerate development with the Search Templates Starter. This guide provides proven prompts and strategies for common development tasks. -## Example: Migrating to Tailwind CSS +## Why use LLMs with Search Templates Starter? -**Prompt:** -> "Replace the existing CSS module structure with a single-tree Tailwind CSS setup. Migrate existing styling from CSS modules to Tailwind utility classes and remove the original CSS module files." +The Search Templates Starter's well-structured codebase and modern tooling make it ideal for AI assistance: -## Example: Adding a new component +- **Consistent patterns** - The organized project structure helps LLMs understand context +- **TypeScript support** - Type information provides better AI suggestions and error detection +- **Component-based architecture** - Clear boundaries make it easier to generate focused code +- **Testing infrastructure** - LLMs can generate tests alongside implementation code -**Prompt:** -> "Create a new `QuickView` component that shows product details in a modal when a button is clicked. The component should be placed in `src/components/QuickView`, and should include a Storybook story file. The modal should be built using the existing `Portal` element." +## Effective Prompting Strategies + +### Include Context +Always provide relevant context about the project structure and existing patterns: + +``` +"In this Preact-based Search Templates Starter project that uses TypeScript, Vite, and follows the component structure in src/components/, create a..." +``` + +### Specify File Locations +Be explicit about where new code should be placed: + +``` +"Create the component in src/components/ProductQuickView/ and include a corresponding Storybook story in the same directory." +``` + +### Reference Existing Patterns +Point to existing code as examples: + +``` +"Following the same pattern as the existing SearchResults component, create a..." +``` + +## Common Development Tasks + +### Adding New Components + +**Prompt Template:** +``` +Create a new [ComponentName] component for the Search Templates Starter project. + +Requirements: +- Place in src/components/[ComponentName]/ +- Use TypeScript and Preact +- Follow the existing component patterns +- Include PropTypes/interface definitions +- Create a Storybook story +- Add basic CSS modules for styling +- Include unit tests with React Testing Library + +The component should [specific functionality requirements]. + +Reference the existing [SimilarComponent] component for patterns. +``` + +**Example: Product Quick View** +``` +Create a new ProductQuickView component for the Search Templates Starter project. + +Requirements: +- Place in src/components/ProductQuickView/ +- Use TypeScript and Preact +- Follow the existing component patterns +- Include PropTypes/interface definitions +- Create a Storybook story +- Add basic CSS modules for styling +- Include unit tests with React Testing Library + +The component should display product details in a modal overlay when triggered, showing product images, name, price, description, and an "Add to Cart" button. Use the existing Portal element for modal rendering. + +Reference the existing SearchResults component for patterns and the Portal element usage. +``` + +### Styling and Theme Changes + +**Example: Migrating to Tailwind CSS** +``` +Replace the existing CSS modules structure in the Search Templates Starter with Tailwind CSS. + +Steps needed: +1. Install and configure Tailwind CSS with Vite +2. Update vite.config.ts to include Tailwind +3. Create a tailwind.config.js with appropriate configuration +4. Replace all CSS module imports and classes with Tailwind utility classes +5. Remove the original CSS module files +6. Update Storybook configuration to support Tailwind +7. Ensure the existing component functionality remains unchanged + +Start with the Button element in src/elements/Button/ as an example, then apply to all components. +``` + +### API Integration + +**Example: Adding Search Filters** +``` +Add advanced filtering functionality to the Search Templates Starter. + +Requirements: +- Create a FilterPanel component in src/components/FilterPanel/ +- Add filter state management to src/contexts/SearchContext.tsx +- Create custom hooks in src/hooks/useFilters.ts for filter logic +- Add filter mapping functions in src/mapping/filterMapping.ts +- Update the search API calls to include filter parameters +- Add TypeScript interfaces for filter data structures +- Include comprehensive tests for filter functionality + +The filters should support: +- Price range filtering +- Category selection +- Brand filtering +- Rating filtering +- Custom attribute filtering + +Reference the existing search implementation patterns and Nosto Search API documentation. +``` + +### Testing + +**Example: Adding E2E Tests** +``` +Create comprehensive end-to-end tests for the Search Templates Starter using Playwright. + +Create tests in test/e2e/ for: +- Basic search functionality +- Autocomplete behavior +- Filter interactions +- Pagination +- Mobile responsive behavior +- Performance testing + +Tests should: +- Use Page Object Model pattern +- Include setup for different merchant configurations +- Test against both mocked and live Nosto data +- Include accessibility testing +- Generate test reports + +Reference the existing test structure and follow Playwright best practices. +``` + +### Performance Optimization + +**Example: Bundle Optimization** +``` +Optimize the Search Templates Starter build for production performance. + +Implement: +- Code splitting for components and routes +- Lazy loading for non-critical components +- Tree shaking optimization in vite.config.ts +- Asset optimization and compression +- Bundle analysis and size monitoring +- Performance monitoring setup + +Focus on: +- Reducing initial bundle size +- Improving Time to Interactive (TTI) +- Optimizing Core Web Vitals +- Maintaining development experience + +Provide before/after bundle analysis and performance metrics. +``` + +## Advanced Use Cases + +### Custom Hook Development + +**Example: Search Analytics Hook** +``` +Create a custom hook useSearchAnalytics in src/hooks/ that: + +- Tracks search events and user interactions +- Integrates with Google Analytics and Nosto Analytics +- Provides search performance metrics +- Handles event batching and error handling +- Includes TypeScript interfaces for analytics data +- Follows the existing hook patterns in the project + +The hook should work with the existing SearchContext and be easily testable. +``` + +### Configuration Management + +**Example: Multi-Environment Config** +``` +Enhance the configuration system in src/config.ts to support multiple environments. + +Requirements: +- Support development, staging, and production configurations +- Environment-specific API endpoints and settings +- Type-safe configuration with TypeScript +- Runtime configuration validation +- Easy switching between configurations +- Integration with Vite environment variables +- Documentation for adding new configuration options + +Follow the existing configuration patterns and maintain backward compatibility. +``` + +## Best Practices for LLM-Assisted Development + +### Code Review +Always review LLM-generated code for: +- Adherence to project patterns and conventions +- TypeScript type safety +- Security considerations +- Performance implications +- Test coverage completeness + +### Iterative Refinement +Start with basic prompts and refine: +1. Get a working implementation +2. Ask for improvements and optimizations +3. Add error handling and edge cases +4. Enhance with additional features +5. Optimize for performance and maintainability + +### Combine with Human Expertise +Use LLMs to: +- Generate boilerplate code quickly +- Explore different implementation approaches +- Create comprehensive test suites +- Document complex functionality + +But rely on human judgment for: +- Architecture decisions +- Security considerations +- Performance trade-offs +- User experience design + +## Troubleshooting LLM Issues + +### Common Problems + +**Generated code doesn't follow project patterns:** +- Include more specific context about existing patterns +- Reference specific files as examples +- Provide the project structure in your prompt + +**TypeScript errors in generated code:** +- Ask the LLM to review and fix TypeScript errors +- Provide the exact error messages for targeted fixes +- Include relevant type definitions in your prompt + +**Tests fail or are incomplete:** +- Request test coverage for specific scenarios +- Ask for tests that follow existing test patterns +- Include example test files for reference + +**Generated code lacks optimization:** +- Ask specifically for performance considerations +- Request code review focusing on optimization +- Include performance requirements in your initial prompt + +By following these patterns and examples, you can significantly accelerate your development workflow while maintaining code quality and project consistency. diff --git a/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md b/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md index 9d93f13..d1cfb3a 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md @@ -1,51 +1,212 @@ # Using the Nosto CLI -The [Nosto CLI](https://github.com/Nosto/nosto-cli) is a powerful command-line tool that allows you to develop and deploy your search templates directly to your Nosto account. This guide covers the essential commands for running the Search Templates Starter with the Nosto CLI. +The [Nosto CLI](https://github.com/Nosto/nosto-cli) is a powerful command-line tool that streamlines the development and deployment workflow for Search Templates Starter projects. It provides seamless integration between your local development environment and your Nosto account. -## Installation +## Why use the Nosto CLI? -The Nosto CLI is already included as a dependency in this project, so you can run it using `npx nosto`. +The Nosto CLI is the recommended way to deploy Search Templates Starter projects because it: -Alternatively, you can install it globally: +- **Automates deployment workflows** - Upload builds and preview changes without manual steps +- **Enables live preview** - See your changes on your actual store with the debug toolbar +- **Integrates with Git** - Respects your `.gitignore` and version control workflow +- **Supports team collaboration** - Multiple developers can work on the same templates +- **Provides safety features** - Preview mode ensures changes are tested before going live + +Since October 2025, the Nosto CLI is the recommended way to work with Search Templates. + +> **Safety Notice** +> If you have concerns about running Nosto CLI on your machine, you can examine the [open source code on GitHub](https://github.com/Nosto/nosto-cli) to ensure it meets your security requirements. + +## Installation and Setup + +### Installation Options + +The Nosto CLI is already included as a dependency in the Search Templates Starter project, so you can run it using `npx`: ```sh -npm install -g @nosto/nosto-cli +npx nosto --help ``` -## Deployment Workflow +For frequent use, you may prefer to install it globally: -Using the Nosto CLI, you can deploy the template straight to your store in a preview mode. Any changes you make will only be visible with the Nosto Debug Toolbar and preview mode enabled on your site. +```sh +npm install -g @nosto/nosto-cli +``` -### 1. Login to Nosto +### Authentication -First, you need to authenticate with your Nosto account. +The Nosto CLI supports two authentication methods: +#### User Account Authentication (Recommended) ```bash npx nosto login ``` +This opens a browser window for secure authentication. Requires 2FA enabled on your Nosto account and stores credentials for 8 hours. This method works across all merchant accounts you have access to. -This command will open a browser window for you to complete the login process. +#### API Key Authentication +Alternatively, you can use a private Search API key in your project configuration. Public API keys are not supported as the CLI requires read-write access. -### 2. Setup the Project +### Project Configuration -Next, create a configuration file for your project. This links your local repository to a specific Nosto merchant account. +Create a `.nosto.json` configuration file in your project root: ```bash npx nosto setup -m YOUR_MERCHANT_ID ``` -Replace `YOUR_MERCHANT_ID` with your actual Nosto account ID. +This creates a minimal configuration file. You can also create it manually: + +```json +{ + "merchant": "your-merchant-id", + "apiUrl": "https://api.nosto.com" +} +``` + +#### Configuration Options + +**Required Configuration:** +- `merchant` - Your Nosto merchant ID (e.g., `shopify-12345678`) + +**Optional Configuration:** +- `apiUrl` - API endpoint (defaults to production `https://api.nosto.com`) +- `apiKey` - Private API key for authentication (if not using user login) + +**Environment Variables:** +You can also use environment variables (they take precedence over the config file): +- `NOSTO_MERCHANT` +- `NOSTO_API_URL` +- `NOSTO_API_KEY` + +## Development Workflow + +### Typical Development Flow + +Once configured, your development workflow typically looks like: + +```bash +# Navigate to your project +cd search-templates-starter + +# Ensure you're logged in +npx nosto login + +# Start development mode with auto-upload +npx nosto st dev + +# Open your store and enable Nosto Debug Toolbar preview mode +# Your changes will appear automatically as you save files +``` + +### Preview Mode Setup + +To see your changes on your live store: -### 3. Run in Development Mode +1. **Enable Debug Toolbar**: Add `?nostodebug=true` to your store URL +2. **Login**: Authenticate when prompted in the debug toolbar +3. **Enable Preview**: Toggle the "Preview" button in the debug toolbar +4. **See Changes**: Refresh your page to see updates as you save files locally -To see your changes live on your site, run the `dev` command: +### Development Commands +#### Development Mode ```bash npx nosto st dev ``` +Watches files for changes and automatically uploads builds for preview. Essential for active development. + +#### Manual Upload +```bash +npx nosto st upload +``` +Uploads the current build without watching for changes. Useful for one-time deployments or testing. + +#### Status Check +```bash +npx nosto status +``` +Shows the current status of your templates and configuration. + +## Production Deployment + +### Promoting to Production + +The Nosto CLI only handles preview deployments. To promote your changes to production: + +1. **Test thoroughly** in preview mode +2. **Navigate** to Nosto Admin UI > Search > Templates +3. **Click** "Deploy latest and launch live" + +> **Important:** Always test your changes thoroughly in preview mode before promoting to production, as this affects all your store visitors. + +### Deployment Safety + +- **Preview First**: All CLI uploads go to preview mode initially +- **Admin Control**: Production deployments require manual approval in the Admin UI +- **Rollback Available**: Previous versions can be restored from the Admin UI if needed + +## Git Integration + +### Recommended Workflow + +The Nosto CLI is designed to work seamlessly with Git: + +```bash +# Create feature branch +git checkout -b feature/new-search-layout + +# Make changes and test with CLI +npx nosto st dev + +# Commit and push changes +git add . +git commit -m "Add new search layout" +git push origin feature/new-search-layout + +# Deploy from main branch after review +git checkout main +git merge feature/new-search-layout +npx nosto st upload +``` + +### File Handling + +The CLI automatically respects your `.gitignore` file when uploading, ensuring that: +- Node modules and build artifacts aren't uploaded unnecessarily +- Sensitive files remain local +- Only source code and assets are deployed + +## Troubleshooting + +### Common Issues + +**Authentication Expired:** +```bash +npx nosto login +``` +Re-authenticate if you see permission errors. + +**Wrong Merchant ID:** +Check your `.nosto.json` file or `NOSTO_MERCHANT` environment variable. + +**Upload Failures:** +- Ensure you have internet connectivity +- Verify your API credentials are valid +- Check that the merchant ID is correct + +**Preview Not Showing:** +- Confirm debug toolbar is enabled (`?nostodebug=true`) +- Ensure preview mode is toggled on +- Try refreshing the page + +### Getting Help -While this command is running, any changes you save to your local files will be automatically uploaded as a preview. You can see the changes by refreshing your store page with the Nosto Debug Toolbar enabled and "Preview" mode toggled on. +- **CLI Help**: Run `npx nosto --help` for command information +- **GitHub Issues**: Report bugs at [github.com/Nosto/nosto-cli](https://github.com/Nosto/nosto-cli) +- **Nosto Support**: Contact support through your Nosto Admin UI -### 4. Production Deployments +## Links and Resources -Once you are happy with your changes in preview mode, you can create a production deployment from the Nosto Admin UI. Navigate to the Search Templates page, and you will be able to promote your latest preview to production. +- **GitHub Repository**: [https://github.com/Nosto/nosto-cli](https://github.com/Nosto/nosto-cli) +- **NPM Package**: [https://www.npmjs.com/package/@nosto/nosto-cli](https://www.npmjs.com/package/@nosto/nosto-cli) +- **Nosto Documentation**: [https://docs.nosto.com/](https://docs.nosto.com/) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md index 658b329..bcc98af 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md @@ -1,28 +1,184 @@ # Project Structure -The Search Templates Starter is organized to promote scalability and maintainability. +The Search Templates Starter is carefully organized to promote scalability, maintainability, and developer productivity. This structure follows modern React/Preact best practices and provides clear separation of concerns. + +## Why this structure? + +This project organization is designed to: + +- **Scale with your project** - Easy to add new features without cluttering the codebase +- **Promote reusability** - Components and utilities can be easily shared and tested +- **Maintain clarity** - Clear separation between different types of code and concerns +- **Support testing** - Dedicated structure for tests and mocks makes testing straightforward +- **Enable collaboration** - Team members can quickly understand and contribute to different areas + +## Directory Overview ``` -/ -├── src/ -│ ├── components/ # Reusable Preact components -│ ├── contexts/ # React contexts for state management -│ ├── elements/ # Atomic UI elements -│ ├── entries/ # Entry points for different modes (native, injected) -│ ├── hooks/ # Custom hooks -│ ├── mapping/ # Data mapping and transformation logic -│ ├── plugins/ # Vite plugins -│ └── utils/ # Utility functions -├── test/ # Test files -│ └── e2e/ # End-to-end tests -├── mocks/ # Mock data for development and testing -├── docs/ # Documentation -└── ... # Configuration files +search-templates-starter/ +├── src/ # Main source code directory +│ ├── components/ # Reusable Preact components +│ ├── contexts/ # React contexts for state management +│ ├── elements/ # Atomic UI elements and building blocks +│ ├── entries/ # Entry points for different modes (native, injected) +│ ├── hooks/ # Custom React hooks +│ ├── mapping/ # Data mapping and transformation logic +│ ├── plugins/ # Vite plugins for build customization +│ ├── utils/ # Utility functions and helpers +│ └── config.ts # Application configuration +├── test/ # Test files and test utilities +│ ├── e2e/ # End-to-end tests with Playwright +│ └── unit/ # Unit and integration tests +├── mocks/ # Mock data for development and testing +├── docs/ # Project documentation +├── .storybook/ # Storybook configuration +├── public/ # Static assets +└── dist/ # Build output (generated) ``` -## Pros of this structure: +## Core Directories Explained + +### `/src/components/` +**Purpose**: Houses reusable UI components that represent complete features or sections. + +**Examples**: +- `SearchResults/` - Complete search results display +- `Autocomplete/` - Autocomplete dropdown functionality +- `FilterPanel/` - Product filtering interface +- `Pagination/` - Navigation between result pages + +**Best Practices**: +- Each component should have its own directory +- Include component file, styles, tests, and Storybook stories +- Components should be self-contained and reusable + +### `/src/elements/` +**Purpose**: Contains atomic UI elements - the smallest building blocks of your interface. + +**Examples**: +- `Button/` - Basic button component +- `Input/` - Form input elements +- `Card/` - Product card layout +- `Portal/` - Portal component for modals + +**Guidelines**: +- Keep elements simple and focused on single responsibility +- Highly reusable across different components +- Minimal business logic, mostly presentation + +### `/src/contexts/` +**Purpose**: React contexts for sharing state across the application. + +**Key Files**: +- `SearchContext.tsx` - Global search state and actions +- `ConfigContext.tsx` - Application configuration +- `ThemeContext.tsx` - Theming and styling state + +**Usage**: +- Provides global state management without heavy libraries +- Makes data available to deeply nested components +- Centralizes state logic for easier testing + +### `/src/hooks/` +**Purpose**: Custom React hooks that encapsulate reusable logic. + +**Examples**: +- `useSearch.ts` - Search functionality and state +- `useDebounce.ts` - Debouncing user input +- `useLocalStorage.ts` - Browser storage integration +- `usePagination.ts` - Pagination logic + +**Benefits**: +- Reusable stateful logic across components +- Easier testing of complex logic +- Clean separation of concerns + +### `/src/entries/` +**Purpose**: Entry points for different application modes. + +**Files**: +- `native.tsx` - Standalone application entry +- `injected.tsx` - Injection into existing sites +- `storybook.tsx` - Storybook-specific setup + +**Why Separate**: +- Different modes may require different initialization +- Allows optimization for specific use cases +- Cleaner build configuration + +### `/src/mapping/` +**Purpose**: Data transformation and mapping between Nosto API responses and component props. + +**Responsibilities**: +- Transform API data to component-friendly formats +- Handle data validation and type safety +- Normalize data from different sources +- Apply business logic to raw data + +### `/src/utils/` +**Purpose**: Pure utility functions that don't depend on React or component state. + +**Examples**: +- `formatPrice.ts` - Price formatting logic +- `searchHelpers.ts` - Search query manipulation +- `validation.ts` - Input validation functions +- `constants.ts` - Application constants + +## Configuration and Build + +### Key Configuration Files + +**`src/config.ts`** +Central configuration for: +- API endpoints and merchant settings +- CSS selectors for site integration +- Feature flags and behavior toggles +- Default search parameters + +**`vite.config.ts`** +Build configuration including: +- Plugin setup and customization +- Build optimization settings +- Development server configuration +- Environment variable handling + +**`.storybook/main.ts`** +Storybook configuration for: +- Component story discovery +- Addon configuration +- Build settings for isolated development + +## Testing Structure + +### `/test/unit/` +Unit and integration tests using Vitest: +- Component testing with React Testing Library +- Hook testing with custom test utilities +- Utility function testing +- Mock setup and test helpers + +### `/test/e2e/` +End-to-end tests with Playwright: +- User workflow testing +- Cross-browser compatibility +- Performance testing +- Integration with live Nosto data + +## Development Workflow Integration + +### Local Development +- `src/` contains all active development code +- Hot reloading watches source files +- TypeScript compilation happens automatically +- Storybook runs parallel for component development + +### Build Process +1. TypeScript compilation with type checking +2. Vite bundling and optimization +3. Asset processing and compression +4. Generation of build artifacts in `dist/` -- **Modularity:** Components are broken down into small, reusable pieces, making them easy to manage and test. -- **Separation of Concerns:** The structure separates components, business logic, and configuration, making the codebase easier to understand and navigate. -- **Scalability:** The organization is designed to scale with your project, allowing you to add new features and components without cluttering the codebase. -- **Testability:** With dedicated directories for tests and mocks, writing and running tests is straightforward. +### Deployment +- CLI tools upload `dist/` contents to Nosto +- Source maps for debugging in production +- Automatic cache busting for updates From 4b54f78d6a007a1f2ec54594a434eed015ed4edc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 15:16:01 +0200 Subject: [PATCH 3/9] fix: structure --- .../implement-search-using-starter/README.md | 2 +- .../project-structure.md | 206 ++++-------------- 2 files changed, 48 insertions(+), 160 deletions(-) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/README.md b/implementing-nosto/implement-search/implement-search-using-starter/README.md index 1b11082..0598e2f 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/README.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/README.md @@ -16,7 +16,7 @@ This approach is ideal when you need advanced customization or when your develop ## Get Started -To start developing with Search Templates Starter, you'll need Node.js 16+ and familiarity with React/Preact. +To start developing with Search Templates Starter, you'll need Node.js 22+ and familiarity with React/Preact. {% content-ref url="getting-started.md" %} [getting-started.md](getting-started.md) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md index bcc98af..527ea0b 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md @@ -1,184 +1,72 @@ # Project Structure -The Search Templates Starter is carefully organized to promote scalability, maintainability, and developer productivity. This structure follows modern React/Preact best practices and provides clear separation of concerns. - -## Why this structure? - -This project organization is designed to: - -- **Scale with your project** - Easy to add new features without cluttering the codebase -- **Promote reusability** - Components and utilities can be easily shared and tested -- **Maintain clarity** - Clear separation between different types of code and concerns -- **Support testing** - Dedicated structure for tests and mocks makes testing straightforward -- **Enable collaboration** - Team members can quickly understand and contribute to different areas +The Search Templates Starter follows a clear, organized structure designed for scalability and maintainability. ## Directory Overview ``` search-templates-starter/ -├── src/ # Main source code directory -│ ├── components/ # Reusable Preact components -│ ├── contexts/ # React contexts for state management -│ ├── elements/ # Atomic UI elements and building blocks -│ ├── entries/ # Entry points for different modes (native, injected) +├── src/ # Main source code +│ ├── components/ # Complete UI components +│ ├── elements/ # Basic UI building blocks +│ ├── entries/ # Application entry points +│ ├── contexts/ # React contexts for state │ ├── hooks/ # Custom React hooks -│ ├── mapping/ # Data mapping and transformation logic -│ ├── plugins/ # Vite plugins for build customization -│ ├── utils/ # Utility functions and helpers -│ └── config.ts # Application configuration -├── test/ # Test files and test utilities -│ ├── e2e/ # End-to-end tests with Playwright -│ └── unit/ # Unit and integration tests -├── mocks/ # Mock data for development and testing -├── docs/ # Project documentation +│ ├── mapping/ # Data transformation logic +│ ├── plugins/ # Vite build plugins +│ ├── utils/ # Utility functions +│ ├── config.ts # Application configuration +│ └── variable.css # CSS custom properties +├── test/ # Testing files +│ ├── e2e/ # End-to-end tests (Playwright) +│ └── mocks/ # Mock data for testing +├── mocks/ # Mock data for development ├── .storybook/ # Storybook configuration -├── public/ # Static assets -└── dist/ # Build output (generated) +└── build/ # Build output (generated) ``` -## Core Directories Explained +## Key Directories -### `/src/components/` -**Purpose**: Houses reusable UI components that represent complete features or sections. +### Components vs Elements -**Examples**: -- `SearchResults/` - Complete search results display -- `Autocomplete/` - Autocomplete dropdown functionality -- `FilterPanel/` - Product filtering interface +**`/src/components/`** - Complete features and UI sections: +- `Autocomplete/` - Search suggestions functionality +- `FilterSidebar/` - Product filtering interface - `Pagination/` - Navigation between result pages +- `Products/` - Product grid display +- `Search/` - Search input and form -**Best Practices**: -- Each component should have its own directory -- Include component file, styles, tests, and Storybook stories -- Components should be self-contained and reusable - -### `/src/elements/` -**Purpose**: Contains atomic UI elements - the smallest building blocks of your interface. - -**Examples**: -- `Button/` - Basic button component -- `Input/` - Form input elements -- `Card/` - Product card layout -- `Portal/` - Portal component for modals - -**Guidelines**: -- Keep elements simple and focused on single responsibility -- Highly reusable across different components -- Minimal business logic, mostly presentation - -### `/src/contexts/` -**Purpose**: React contexts for sharing state across the application. - -**Key Files**: -- `SearchContext.tsx` - Global search state and actions -- `ConfigContext.tsx` - Application configuration -- `ThemeContext.tsx` - Theming and styling state - -**Usage**: -- Provides global state management without heavy libraries -- Makes data available to deeply nested components -- Centralizes state logic for easier testing - -### `/src/hooks/` -**Purpose**: Custom React hooks that encapsulate reusable logic. - -**Examples**: -- `useSearch.ts` - Search functionality and state -- `useDebounce.ts` - Debouncing user input -- `useLocalStorage.ts` - Browser storage integration -- `usePagination.ts` - Pagination logic - -**Benefits**: -- Reusable stateful logic across components -- Easier testing of complex logic -- Clean separation of concerns +**`/src/elements/`** - Basic UI building blocks: +- `Button/` - Button component +- `Checkbox/` - Form checkbox +- `Icon/` - Icon system +- `Portal/` - Portal for modals and overlays -### `/src/entries/` -**Purpose**: Entry points for different application modes. +### Application Structure -**Files**: -- `native.tsx` - Standalone application entry +**`/src/entries/`** - Different app modes: +- `native.tsx` - Standalone application - `injected.tsx` - Injection into existing sites -- `storybook.tsx` - Storybook-specific setup -**Why Separate**: -- Different modes may require different initialization -- Allows optimization for specific use cases -- Cleaner build configuration +**`/src/contexts/`** - State management: +- React contexts for sharing state across components -### `/src/mapping/` -**Purpose**: Data transformation and mapping between Nosto API responses and component props. +**`/src/hooks/`** - Reusable logic: +- Custom hooks for search functionality and UI interactions -**Responsibilities**: -- Transform API data to component-friendly formats -- Handle data validation and type safety -- Normalize data from different sources -- Apply business logic to raw data +**`/src/mapping/`** - Data handling: +- Transform API responses to component-friendly formats +- URL state management +- Tagging integration -### `/src/utils/` -**Purpose**: Pure utility functions that don't depend on React or component state. +## Configuration -**Examples**: -- `formatPrice.ts` - Price formatting logic -- `searchHelpers.ts` - Search query manipulation -- `validation.ts` - Input validation functions -- `constants.ts` - Application constants - -## Configuration and Build - -### Key Configuration Files - -**`src/config.ts`** -Central configuration for: -- API endpoints and merchant settings -- CSS selectors for site integration -- Feature flags and behavior toggles +**`src/config.ts`** - Central configuration for: +- API settings and merchant configuration +- CSS selectors for site integration - Default search parameters +- Hit decorators (thumbnails, pricing) -**`vite.config.ts`** -Build configuration including: -- Plugin setup and customization -- Build optimization settings -- Development server configuration -- Environment variable handling - -**`.storybook/main.ts`** -Storybook configuration for: -- Component story discovery -- Addon configuration -- Build settings for isolated development - -## Testing Structure - -### `/test/unit/` -Unit and integration tests using Vitest: -- Component testing with React Testing Library -- Hook testing with custom test utilities -- Utility function testing -- Mock setup and test helpers - -### `/test/e2e/` -End-to-end tests with Playwright: -- User workflow testing -- Cross-browser compatibility -- Performance testing -- Integration with live Nosto data - -## Development Workflow Integration - -### Local Development -- `src/` contains all active development code -- Hot reloading watches source files -- TypeScript compilation happens automatically -- Storybook runs parallel for component development - -### Build Process -1. TypeScript compilation with type checking -2. Vite bundling and optimization -3. Asset processing and compression -4. Generation of build artifacts in `dist/` - -### Deployment -- CLI tools upload `dist/` contents to Nosto -- Source maps for debugging in production -- Automatic cache busting for updates +**`vite.config.ts`** - Build configuration +**`.storybook/`** - Component development environment +**`nosto.config.ts`** - Nosto CLI integration From 690bd38bf9d6547a3baf1d21d4d42469edfb0ca7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 16:18:35 +0200 Subject: [PATCH 4/9] docs: summery --- SUMMARY.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/SUMMARY.md b/SUMMARY.md index aab3b3d..e09fac0 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -36,6 +36,11 @@ * [Implementing Category pages](implementing-nosto/implement-search/getting-started-with-nosto-search/implementing-category-pages.md) * [Testing & deployment](implementing-nosto/implement-search/implement-search-using-code-editor/testing-and-deployment.md) * [FAQ](implementing-nosto/implement-search/implement-search-using-code-editor/faq.md) + * [Using Search Templates Starter](implementing-nosto/implement-search/implement-search-using-starter/README.md) + * [Getting started](implementing-nosto/implement-search/implement-search-using-starter/getting-started.md) + * [Using Nosto CLI](implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md) + * [Project structure](implementing-nosto/implement-search/implement-search-using-starter/project-structure.md) + * [LLM examples](implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md) * [Using the API](implementing-nosto/implement-search/implement-search-using-api/README.md) * [Use the Search & Categories API](implementing-nosto/implement-search/implement-search-using-api/using-the-search-api.md) * [Implement Search results page](implementing-nosto/implement-search/implement-search-using-api/implementing-search-page.md) From 8f385ee68d83d7a6341cde8f9c75cc1aece1c4b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 16:20:14 +0200 Subject: [PATCH 5/9] fix: reviews --- .../implement-search-using-starter/getting-started.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md index 1ab2e0c..2bc9038 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -1,7 +1,5 @@ # Getting Started -This guide will walk you through setting up and running the Search Templates Starter project on your local machine for development. - ## Why use the Search Templates Starter? The Search Templates Starter provides a complete development environment for building custom search experiences with modern tools and practices. It's designed for developers who need: From 7d925af8f7954ccc86ac95fec281b4100d36425c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 16:36:25 +0200 Subject: [PATCH 6/9] fix: reviews --- .../getting-started.md | 62 +++++++++++++------ .../llm-examples.md | 7 +++ 2 files changed, 49 insertions(+), 20 deletions(-) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md index 2bc9038..4b9e595 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -23,7 +23,18 @@ Before you begin, ensure you have the following installed on your system: ### 1. Clone the repository -First, clone the Search Templates Starter repository to your local machine: +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: Command line** +```sh +git clone https://github.com/nosto/search-templates-starter.git +cd search-templates-starter +``` + +**Option 2: GitHub UI** +1. Go to [Search Templates Starter on GitHub](https://github.com/nosto/search-templates-starter) +2. Click the **Code** button and select **Download ZIP** or **Open with GitHub Desktop** +3. Extract the ZIP file or clone the repository using your preferred Git client ```sh git clone https://github.com/nosto/search-templates-starter.git @@ -35,7 +46,7 @@ cd search-templates-starter Install the required npm packages: ```sh -npm install +npm ci ``` This will install all necessary dependencies including: @@ -51,17 +62,17 @@ This will install all necessary dependencies including: The Search Templates Starter requires your Nosto merchant ID to connect to your search data. You can provide this in two ways: -**Option 1: Environment Variable** -```bash -VITE_MERCHANT_ID=your-merchant-id npm run dev -``` - -**Option 2: Environment File** +**Option 1: Environment File (Recommended)** Create a `.env` file in the root of the project: ``` VITE_MERCHANT_ID=your-merchant-id ``` +**Option 2: Environment Variable** +```bash +VITE_MERCHANT_ID=your-merchant-id npm run dev +``` + > **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 @@ -83,28 +94,39 @@ npm run dev This will launch the application at `http://localhost:8000` with hot reloading enabled. Any changes you make to the source code will be automatically reflected in the browser. -### Understanding Development Modes +> **Important:** The local development server runs independently of your shop's styles. To see how your components will look with your shop's styling, you can: +> - Modify `index.html` to reference your shop's CSS files +> - Use the `nosto-cli watch` workflow for live deployment testing +> - Test directly on your shop's staging environment -The Search Templates Starter supports multiple development modes to accommodate different workflows: +### Understanding Development Modes -#### Native Mode -```bash -npm run dev:native -``` -In this mode, the application renders as a standalone Preact app. This is useful for: -- Developing components in isolation -- Testing search functionality without a live site -- Rapid prototyping of new features +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 +#### Injected Mode (Default) ```bash npm run dev ``` -This is the default mode where search components are injected into a live site using React Portals. To use this mode effectively: +In this mode, the components are rendered into the page using [React Portals](https://react.dev/reference/react-dom/createPortal), targeting the elements you define with CSS selectors in `src/config.tsx`. 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` + +To use this mode effectively: 1. Configure CSS selectors in `src/config.ts` to match your site's elements 2. Ensure your site is accessible for injection 3. Test on your actual store to see real integration +#### Native Mode +```bash +npm run dev:native +``` +In this mode, the Starter behaves like a standard React/Preact app. It creates the component tree and renders it normally into the document body. 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. diff --git a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md index c653d92..60a350e 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md @@ -13,6 +13,13 @@ The Search Templates Starter's well-structured codebase and modern tooling make ## Effective Prompting Strategies +### Follow Standard Development Patterns +The Search Templates Starter includes standard development patterns and documentation that LLMs can leverage: + +- **AGENTS.md** - Contains specific prompting patterns and conventions for the project +- **Copilot Instructions** - Pre-configured GitHub Copilot instructions are included in the repository and should be customized for your specific use case +- **README patterns** - Follow the established documentation structure for consistency + ### Include Context Always provide relevant context about the project structure and existing patterns: From ed338e719a5ca86dadd327b0ddb6ac2d4cb8ab66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 16:45:03 +0200 Subject: [PATCH 7/9] fix: reviews --- .../implement-search-using-starter/llm-examples.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md index 60a350e..22636d5 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md @@ -16,10 +16,12 @@ The Search Templates Starter's well-structured codebase and modern tooling make ### Follow Standard Development Patterns The Search Templates Starter includes standard development patterns and documentation that LLMs can leverage: -- **AGENTS.md** - Contains specific prompting patterns and conventions for the project +- **AGENTS.md Standard** - Follow the [agents.md](https://agents.md/) standardized pattern for providing AI coding agents with project-specific context, build commands, code style guidelines, and testing instructions - **Copilot Instructions** - Pre-configured GitHub Copilot instructions are included in the repository and should be customized for your specific use case - **README patterns** - Follow the established documentation structure for consistency +> **Tip:** Consider creating an `AGENTS.md` file in your project root following the [agents.md standard](https://agents.md/) to provide consistent context for all AI coding tools. + ### Include Context Always provide relevant context about the project structure and existing patterns: From 42d82d3499f6566c5c5db82fd4f8285084647025 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 17:19:32 +0200 Subject: [PATCH 8/9] fix: reviews --- SUMMARY.md | 10 +++++----- .../implement-search-using-starter/getting-started.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index e09fac0..110444d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -28,6 +28,11 @@ * [Implement on native mobile](implementing-nosto/implement-on-native-mobile.md) * [Implement on a physical store](implementing-nosto/implement-on-physical-store.md) * [Implement Search & Categories](implementing-nosto/implement-search/README.md) + * [Using Search Templates Starter](implementing-nosto/implement-search/implement-search-using-starter/README.md) + * [Getting started](implementing-nosto/implement-search/implement-search-using-starter/getting-started.md) + * [Using Nosto CLI](implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md) + * [Project structure](implementing-nosto/implement-search/implement-search-using-starter/project-structure.md) + * [LLM examples](implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md) * [Using Search Templates](implementing-nosto/implement-search/implement-search-using-code-editor/README.md) * [Using Search Templates](implementing-nosto/implement-search/implement-search-using-code-editor/using-the-code-editor.md) * [Using Nosto CLI](implementing-nosto/implement-search/implement-search-using-code-editor/using-nosto-cli.md) @@ -36,11 +41,6 @@ * [Implementing Category pages](implementing-nosto/implement-search/getting-started-with-nosto-search/implementing-category-pages.md) * [Testing & deployment](implementing-nosto/implement-search/implement-search-using-code-editor/testing-and-deployment.md) * [FAQ](implementing-nosto/implement-search/implement-search-using-code-editor/faq.md) - * [Using Search Templates Starter](implementing-nosto/implement-search/implement-search-using-starter/README.md) - * [Getting started](implementing-nosto/implement-search/implement-search-using-starter/getting-started.md) - * [Using Nosto CLI](implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md) - * [Project structure](implementing-nosto/implement-search/implement-search-using-starter/project-structure.md) - * [LLM examples](implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md) * [Using the API](implementing-nosto/implement-search/implement-search-using-api/README.md) * [Use the Search & Categories API](implementing-nosto/implement-search/implement-search-using-api/using-the-search-api.md) * [Implement Search results page](implementing-nosto/implement-search/implement-search-using-api/implementing-search-page.md) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md index 4b9e595..65ca89e 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -120,7 +120,7 @@ To use this mode effectively: ```bash npm run dev:native ``` -In this mode, the Starter behaves like a standard React/Preact app. It creates the component tree and renders it normally into the document body. This is useful for: +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 From 5ee51fd708c10ac3e19e56d69b253441e469ab27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomas=20Jaseli=C5=ABnas?= Date: Thu, 30 Oct 2025 17:32:44 +0200 Subject: [PATCH 9/9] fix: reviews --- .../getting-started.md | 26 ++- .../llm-examples.md | 159 ++---------------- 2 files changed, 29 insertions(+), 156 deletions(-) diff --git a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md index 65ca89e..5315fd4 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -25,17 +25,12 @@ Before you begin, ensure you have the following installed on your system: 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: Command line** -```sh -git clone https://github.com/nosto/search-templates-starter.git -cd search-templates-starter -``` - -**Option 2: GitHub UI** +**Option 1: GitHub UI (Recommended)** 1. Go to [Search Templates Starter on GitHub](https://github.com/nosto/search-templates-starter) -2. Click the **Code** button and select **Download ZIP** or **Open with GitHub Desktop** -3. Extract the ZIP file or clone the repository using your preferred Git client +2. Click the **Use this template** button to create your own repository, or click **Code** and select **Download ZIP** or **Open with GitHub Desktop** +3. If using the template feature, clone your new repository; if downloading, extract the ZIP file +**Option 2: Command Line** ```sh git clone https://github.com/nosto/search-templates-starter.git cd search-templates-starter @@ -49,12 +44,7 @@ Install the required npm packages: npm ci ``` -This will install all necessary dependencies including: -- Preact for the UI framework -- Vite for build tooling and development server -- TypeScript for type safety -- Vitest for testing -- Storybook for component development +This will install all necessary dependencies for the project. ## Configuration @@ -68,6 +58,12 @@ Create a `.env` file in the root of the project: VITE_MERCHANT_ID=your-merchant-id ``` +For Shopify merchants, you may also want to configure your store URL: +``` +VITE_MERCHANT_ID=your-merchant-id +VITE_SHOPIFY_STORE_URL=https://your-store.myshopify.com +``` + **Option 2: Environment Variable** ```bash VITE_MERCHANT_ID=your-merchant-id npm run dev diff --git a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md index 22636d5..446336c 100644 --- a/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md +++ b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md @@ -45,168 +45,45 @@ Point to existing code as examples: ## Common Development Tasks -### Adding New Components +### Component Modifications -**Prompt Template:** +**Example: Replace FilterSidebar with FilterTopbar** ``` -Create a new [ComponentName] component for the Search Templates Starter project. +Replace the existing FilterSidebar component with a FilterTopbar component that displays filters horizontally at the top of the search results. -Requirements: -- Place in src/components/[ComponentName]/ -- Use TypeScript and Preact -- Follow the existing component patterns -- Include PropTypes/interface definitions -- Create a Storybook story -- Add basic CSS modules for styling -- Include unit tests with React Testing Library - -The component should [specific functionality requirements]. - -Reference the existing [SimilarComponent] component for patterns. +Update the layout in Serp component to render FilterTopbar above the products grid instead of FilterSidebar in the sidebar. Maintain all existing filter functionality while adapting the responsive design for horizontal layout. ``` -**Example: Product Quick View** +**Example: Replace Pills with Checkboxes in Filters** ``` -Create a new ProductQuickView component for the Search Templates Starter project. - -Requirements: -- Place in src/components/ProductQuickView/ -- Use TypeScript and Preact -- Follow the existing component patterns -- Include PropTypes/interface definitions -- Create a Storybook story -- Add basic CSS modules for styling -- Include unit tests with React Testing Library +Replace the Pill components used in FilterSidebar with checkbox inputs for better accessibility and mobile usability. -The component should display product details in a modal overlay when triggered, showing product images, name, price, description, and an "Add to Cart" button. Use the existing Portal element for modal rendering. - -Reference the existing SearchResults component for patterns and the Portal element usage. +Update the filter display to show checkboxes with labels instead of pill-style buttons, while maintaining the same filter state management and visual feedback for selected filters. ``` -### Styling and Theme Changes +### Styling Changes -**Example: Migrating to Tailwind CSS** -``` -Replace the existing CSS modules structure in the Search Templates Starter with Tailwind CSS. - -Steps needed: -1. Install and configure Tailwind CSS with Vite -2. Update vite.config.ts to include Tailwind -3. Create a tailwind.config.js with appropriate configuration -4. Replace all CSS module imports and classes with Tailwind utility classes -5. Remove the original CSS module files -6. Update Storybook configuration to support Tailwind -7. Ensure the existing component functionality remains unchanged - -Start with the Button element in src/elements/Button/ as an example, then apply to all components. +**Example: Replace CSS Modules with Tailwind** ``` +Convert the Button component from CSS modules to Tailwind CSS classes. -### API Integration - -**Example: Adding Search Filters** -``` -Add advanced filtering functionality to the Search Templates Starter. - -Requirements: -- Create a FilterPanel component in src/components/FilterPanel/ -- Add filter state management to src/contexts/SearchContext.tsx -- Create custom hooks in src/hooks/useFilters.ts for filter logic -- Add filter mapping functions in src/mapping/filterMapping.ts -- Update the search API calls to include filter parameters -- Add TypeScript interfaces for filter data structures -- Include comprehensive tests for filter functionality - -The filters should support: -- Price range filtering -- Category selection -- Brand filtering -- Rating filtering -- Custom attribute filtering - -Reference the existing search implementation patterns and Nosto Search API documentation. +Replace the current Button.module.css imports and className usage with Tailwind utility classes, maintaining the same visual appearance and hover states. ``` -### Testing +### Search Functionality -**Example: Adding E2E Tests** +**Example: Add Voice Search to Autocomplete** ``` -Create comprehensive end-to-end tests for the Search Templates Starter using Playwright. - -Create tests in test/e2e/ for: -- Basic search functionality -- Autocomplete behavior -- Filter interactions -- Pagination -- Mobile responsive behavior -- Performance testing - -Tests should: -- Use Page Object Model pattern -- Include setup for different merchant configurations -- Test against both mocked and live Nosto data -- Include accessibility testing -- Generate test reports - -Reference the existing test structure and follow Playwright best practices. -``` - -### Performance Optimization +Integrate the existing SpeechToTextButton component into the main search input in the Serp component. -**Example: Bundle Optimization** +Position the voice search button inside the search input field and ensure it works consistently across both autocomplete and main search interfaces. ``` -Optimize the Search Templates Starter build for production performance. - -Implement: -- Code splitting for components and routes -- Lazy loading for non-critical components -- Tree shaking optimization in vite.config.ts -- Asset optimization and compression -- Bundle analysis and size monitoring -- Performance monitoring setup - -Focus on: -- Reducing initial bundle size -- Improving Time to Interactive (TTI) -- Optimizing Core Web Vitals -- Maintaining development experience - -Provide before/after bundle analysis and performance metrics. -``` - -## Advanced Use Cases - -### Custom Hook Development - -**Example: Search Analytics Hook** -``` -Create a custom hook useSearchAnalytics in src/hooks/ that: - -- Tracks search events and user interactions -- Integrates with Google Analytics and Nosto Analytics -- Provides search performance metrics -- Handles event batching and error handling -- Includes TypeScript interfaces for analytics data -- Follows the existing hook patterns in the project -The hook should work with the existing SearchContext and be easily testable. +**Example: Replace Infinite Scroll with Load More Button** ``` +Replace the current pagination in search results with a "Load More" button that appends new results to the existing list. -### Configuration Management - -**Example: Multi-Environment Config** -``` -Enhance the configuration system in src/config.ts to support multiple environments. - -Requirements: -- Support development, staging, and production configurations -- Environment-specific API endpoints and settings -- Type-safe configuration with TypeScript -- Runtime configuration validation -- Easy switching between configurations -- Integration with Vite environment variables -- Documentation for adding new configuration options - -Follow the existing configuration patterns and maintain backward compatibility. +Update the Pagination component to show a centered button instead of page numbers, and modify the search state to accumulate results rather than replace them. ``` ## Best Practices for LLM-Assisted Development