diff --git a/SUMMARY.md b/SUMMARY.md index aab3b3d..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) 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..0598e2f --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/README.md @@ -0,0 +1,37 @@ +# Implement Search using Search Templates Starter + +The Search Templates Starter is a Preact-based starter template that provides a complete development environment for building custom search experiences with Nosto. + +## Why use Search Templates Starter? + +Search Templates Starter allows you to build fully custom search implementations with modern development practices. You get: + +- **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 + +This approach is ideal when you need advanced customization or when your development team prefers working with familiar local tools and workflows. + +## Get Started + +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) +{% 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 new file mode 100644 index 0000000..5315fd4 --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/getting-started.md @@ -0,0 +1,206 @@ +# Getting Started + +## 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 + +Before you begin, ensure you have the following installed on your system: + +- **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 + +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)** +1. Go to [Search Templates Starter on GitHub](https://github.com/nosto/search-templates-starter) +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 +``` + +### 2. Install dependencies + +Install the required npm packages: + +```sh +npm ci +``` + +This will install all necessary dependencies for the project. + +## Configuration + +### 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 File (Recommended)** +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 +``` + +> **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. + +> **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 + +### Understanding Development 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) +```bash +npm run dev +``` +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 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 provides an isolated environment for developing and testing individual components: + +```sh +npm run storybook +``` + +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 +``` + +**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. + +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 new file mode 100644 index 0000000..446336c --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/llm-examples.md @@ -0,0 +1,144 @@ +# Utilizing LLMs for Development + +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. + +## Why use LLMs with Search Templates Starter? + +The Search Templates Starter's well-structured codebase and modern tooling make it ideal for AI assistance: + +- **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 + +## Effective Prompting Strategies + +### Follow Standard Development Patterns +The Search Templates Starter includes standard development patterns and documentation that LLMs can leverage: + +- **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: + +``` +"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 + +### Component Modifications + +**Example: Replace FilterSidebar with FilterTopbar** +``` +Replace the existing FilterSidebar component with a FilterTopbar component that displays filters horizontally at the top of the search results. + +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: Replace Pills with Checkboxes in Filters** +``` +Replace the Pill components used in FilterSidebar with checkbox inputs for better accessibility and mobile usability. + +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 Changes + +**Example: Replace CSS Modules with Tailwind** +``` +Convert the Button component from CSS modules to Tailwind CSS classes. + +Replace the current Button.module.css imports and className usage with Tailwind utility classes, maintaining the same visual appearance and hover states. +``` + +### Search Functionality + +**Example: Add Voice Search to Autocomplete** +``` +Integrate the existing SpeechToTextButton component into the main search input in the Serp component. + +Position the voice search button inside the search input field and ensure it works consistently across both autocomplete and main search interfaces. +``` + +**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. + +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 + +### 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 new file mode 100644 index 0000000..d1cfb3a --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/nosto-cli.md @@ -0,0 +1,212 @@ +# Using 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. + +## Why use the Nosto CLI? + +The Nosto CLI is the recommended way to deploy Search Templates Starter projects because it: + +- **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 +npx nosto --help +``` + +For frequent use, you may prefer to install it globally: + +```sh +npm install -g @nosto/nosto-cli +``` + +### Authentication + +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. + +#### 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. + +### Project Configuration + +Create a `.nosto.json` configuration file in your project root: + +```bash +npx nosto setup -m YOUR_MERCHANT_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: + +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 + +### 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 + +- **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 + +## Links and Resources + +- **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 new file mode 100644 index 0000000..527ea0b --- /dev/null +++ b/implementing-nosto/implement-search/implement-search-using-starter/project-structure.md @@ -0,0 +1,72 @@ +# Project Structure + +The Search Templates Starter follows a clear, organized structure designed for scalability and maintainability. + +## Directory Overview + +``` +search-templates-starter/ +├── 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 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 +└── build/ # Build output (generated) +``` + +## Key Directories + +### Components vs Elements + +**`/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 + +**`/src/elements/`** - Basic UI building blocks: +- `Button/` - Button component +- `Checkbox/` - Form checkbox +- `Icon/` - Icon system +- `Portal/` - Portal for modals and overlays + +### Application Structure + +**`/src/entries/`** - Different app modes: +- `native.tsx` - Standalone application +- `injected.tsx` - Injection into existing sites + +**`/src/contexts/`** - State management: +- React contexts for sharing state across components + +**`/src/hooks/`** - Reusable logic: +- Custom hooks for search functionality and UI interactions + +**`/src/mapping/`** - Data handling: +- Transform API responses to component-friendly formats +- URL state management +- Tagging integration + +## Configuration + +**`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 +**`.storybook/`** - Component development environment +**`nosto.config.ts`** - Nosto CLI integration