jsApi

Пакет предназначен для разработчиков встроенных приложений и предоставляет инструменты для улучшения и оптимизации процесса разработки. Пакет предоставляет:

• Функцию initializeJsApi для подключения jsApi в разных режимах (development, test, production)
• Файлы декларации типов .d.ts для jsApi при работе с TypeScript
• Mock-функции jsApi для локальной разработки, а также инструменты для их переопределения и уточнения
• Инструменты для локальной разработки с проксированием запросов к приложению

Содержание

• Быстрый старт
• Инициализация jsApi
• Переопределение методов jsApi
• Типизация jsApi
• Настройка проксирования запросов

Быстрый старт

1. Установить пакет: npm i --save-dev @nsmp/js-api
2. Инициализировать jsApi в проекте - Инициализация jsApi
3. В режиме разработки (при необходимости):
   1. переопределить стандартные методы jsApi - Переопределение методов jsApi
   2. настроить проксирование запросов - Настройка проксирования запросов

К содержанию

Инициализация jsApi

Для того чтобы методы jsApi работали во встроенном приложении, необходимо инициализировать их в проекте. Для инициализации jsApi необходимо вызвать функцию initializeJsApi из @nsmp/js-api. Функция принимает аргументы:

• mock?: JsApi - моковый jsApi, определенный во встроенном приложении. Если передан, то переопределит стандартные функции jsApi - Переопределение методов jsApi

Пример:

import {initializeJsApi} from '@nsmp/js-api';

// В режиме разработки будут использоваться методы jsApi, которые определены в пакете @nsmp/js-api
initializeJsApi()
  .then(() => {
     // Рендер приложения
  })
  .catch((e) => {
    console.error(e)
  })

Или

import {initializeJsApi} from '@nsmp/js-api';
import mockJsApi from 'mocks/mockJsApi';

// В режиме разработки методы из переменной mockJsApi переопределят методы jsApi, которые есть в библиотеке
initializeJsApi(mockJsApi)
  .then(() => {
     // Рендер приложения
  })
  .catch((e) => {
    console.error(e)
  })

К содержанию

Переопределение методов jsApi

В пакете есть возможность переопределить стандартные методы. Для этого необходимо создать переменную в проекте, которая будет хранить новые значения методов jsApi, например:

import {PartialJsApi} from '@nsmp/js-api';

// При работе с TypeScript указан тип PartialJsApi
const mockJsApi: PartialJsApi = {
	extractSubjectUuid () {
		return 'subjectUuid$123';
	},
	findContentCode () {
		return 'contentCode';
	},
	getCurrentUser () {
		return {
			uuid: 'user$123'
		};
	},
	urls: {
		objectCard: (uuid: string) => `/${uuid}`
	}
};

При работе с TypeScript переменной с моковыми методами jsApi можно указать тип PartialJsApi из данного пакета - Типизация jsApi

К содержанию

Типизация jsApi

В пакете определены типы для методов jsApi для разработки приложений с использованием TypeScript:

• JsApi - содержит все методы jsApi. При его использовании необходимо задать все методы, которые определены в пакете jsApi, все методы будут заменены новыми
• PartialJsApi - также содержит все методы jsApi. Но при его использовании можно задать только те методы, которые необходимо переопределить, остальные методы останутся без изменений

Если нужно создать моки с частичным переопределением функций, а затем передать их в initializeJsApi, следует использовать тип PartialJsApi при создании моков.

Пример:

import {PartialJsApi} from '@nsmp/js-api';

const mock: PartialJsApi = {
  extractSubjectUuid () {
    return 'subjectUuid$123';
  },
  findContentCode () {
    return 'contentCode';
  },
}

initializeJsApi(mock)

К содержанию

Настройка проксирования запросов

Пакет имеет возможность проксирования запросов в режиме локальной разработки приложения. Чтобы проксирование запросов работало правильно, необходимо создать файл dev.env и определить переменные окружения:

• ACCESS_KEY - ключ доступа для REST запросов
• APP_URL - URL стенда
• APP_CODE - код ВП, примеч. код ВП и код контента должны совпадать
• REST_PATH - путь REST запроса (rest или earest)
• SUBJECT_UUID - идентификатор объекта, на котором выведено ВП
• USER_LOGIN - логин пользователя
• USER_UUID - идентификатор пользователя

Пример:

ACCESS_KEY=your-access-key
APP_URL=https://your-domain.ru/
APP_CODE=app_code
REST_PATH=earest
SUBJECT_UUID=subject$123
USER_LOGIN=your_login
USER_UUID=user$123

Также необходимо изменить строку запуска dev режима приложения в файле package.json, например:

• Было - "dev": "cross-env NODE_ENV=development webpack serve --mode=development --config ./webpack/config.js"
• Стало - "dev": "cross-env NODE_ENV=development start-webpack-server --mode=development --config ./webpack/config.js --env ./dev.env"

config и env являются опциональными аргументами командной строки. Если они не указаны по стандарту будут браться пути:

• config - ./webpack/config.js
• env - ./dev.env

Команда start-webpack-server запускает webpack server с добавленным в него проксированием запросов и всеми переменными окружения из файла dev.env

К содержанию