Deployment and Development

This guide describes the development, building, and deployment process for UpSearch Plugin.

Development Environment

Requirements

• Node.js 14.19.3 (recommended to use Volta)
• npm

Environment Variables

Create a .env file in the project root:

API_TOKEN=your_api_token           # Token for UpSearch API access
POEDITOR_TOKEN=poeditor_token      # Token for POEditor (translations)
POEDITOR_PROJECT_ID=project_id     # Project ID in POEditor

info

These variables are only needed for development, not for production build.

Installing Dependencies

npm install

Running Dev Server

npm run dev

Opens a development server at http://localhost:8080/ with demo pages.

Running Storybook

npm run storybook

Storybook with UI components runs at http://localhost:6006/.

Build

Production Build

npm run build

Creates a production build in the build/ folder:

• upSearchSuggest.js - Autocomplete component
• upSearchResults.js - Results component
• upsearch.css - Styles
• storybook/ - Storybook documentation

Application Only (without Storybook)

npm run build-app

Build with ZIP Archive

npm run dist

Git Workflow

Branches

• master - Main branch with stable script version
• subdomain_domain_extension - Customer branches (e.g., www_fotoskoda_cz)

Creating a Customer Version

1. Create a new branch from the master branch:

   git checkout master
   git checkout -b www_domain_name_cz

2. Modify deploy properties (testing.properties and production.properties):

   # testing.properties
   remote.dir=/data/www/cdn2.upsearch.cz/projects/www_domain_name_cz/
   
   # production.properties
   remote.dir=/data/www/cdn.upsearch.cz/projects/www_domain_name_cz/

3. Create deploy projects in PHPCI at https://deploy3.praguebest.cz/:

   • Admin options -> Add Project
   • Type: GitLab
   • URL: git@gitlab.praguebest.cz:internal/upsearch-plugin.git
   • Name: e.g., UpSearch Plugin - ClientName - testing/production
   • PHPCI config: copy from phpCiConfigTesting.yml or phpCiConfigProduction.yml
   • Branch: your branch name
   • Group: UpSearch

4. Set up webhooks in GitLab (Settings -> Webhooks):

   • URL: https://deploy3.praguebest.cz/webhook/gitlab/<project_id>
   • Testing: Trigger = Push events, Branch = your branch
   • Production: Trigger = Tag push events

5. Create folder on server in projects/ (e.g., www_domain_name_cz)

Deploy

Testing

Push to branch automatically triggers deploy to testing CDN:

git push origin www_domain_name_cz

Result will be available at: https://cdn2.upsearch.cz/projects/www_domain_name_cz/

Production

Tag push triggers deploy to production CDN:

# Tag format: <branch_name>/<tag_name>
git tag www_domain_name_cz/v1.0.0
git push origin www_domain_name_cz/v1.0.0

Result will be available at: https://cdn.upsearch.cz/projects/www_domain_name_cz/

Tag Naming

Tag name must have the format <branch_name>/<tag_name>, e.g.:

• master/v1.0.1
• www_fotoskoda_cz/v1.0.1

Localization

Adding New Text

1. Use FormattedMessage or formatMessage in code:

   <FormattedMessage
     defaultMessage="Search..."
     description="Placeholder for search field"
   />

2. Extract texts:

   npm run trans:extract

3. Upload to POEditor and translate

4. Download translations and compile:

   npm run trans:download
   npm run trans:compile

Adding a New Language

1. Add JSON file to src/app/i18n/translated/
2. Run compilation: npm run trans:compile
3. Add language to src/app/i18n/translations.ts

API

Frontend communicates with backend via REST API (https://api.upsearch.cz).

Generating API Client

API client is generated from OpenAPI specification:

npm run generate-api

Output is in src/app/api/client-generated/.

Scripts

Script	Description
npm run dev	Starts dev server
npm run build	Creates production build
npm run build-app	Build application only
npm run storybook	Starts Storybook
npm run lint	Runs ESLint
npm run format	Formats code using Prettier
npm run trans:extract	Extracts texts for translation
npm run trans:compile	Compiles translations
npm run generate-api	Generates API client