Разработка приложений SharePoint на React с использованием sp-rest-proxy

Вступление

React очень полярен и любим разработчиками по всему миру когда речь заходит о создании модульных компонент и приложений. Как большинство современных инструментов, React в том чисте обладает общирной экосистемой инструментов в том числе для шаблонизации создания новых проектов и процессов сборки. Но, когда требуется использованить штатные средства инструментариев React совместно с SharePoint, команде или отдельно взятому разработчику может потребоваться порядочно времени, чтобы наладить процесс до желаемого состояния "пишем код, сосредотачиваемся на бизнес-логике, остальное закрывается тулчейнами".

К счастью, для сложных задач есть простые пути решения, когда кто-то уже сделал это за вас. Данная статья является гайдом по настройке типового React приложения для работы с API SharePoint (Online, 2019/2016/2013) напрямую без необходимости развертывания кода.

Пререквизиты

Для простоты используется create-react-app, т.к. любой имеющий дело с React разработчик в той или иной мере знаком с этим генератором. CRA должен быть установлен глобально, либо можно использовать npx. Конечно же, т.к. дело обстоит в клиентской разработке, Node.js и NPM так же должны быть установлены. Более подробно о настройке рабочей станциии для современной front-end разработки можно почитать здесь, однако, задающиеся вопросом "как разрабатывать с помощью React для SharePoint" вряд ли не в курсе общих вещей, поэтому нищадно пропускаю эти моменты.

Порядок действий

1. Создать и перейти в проект CRA:

create-react-app sharepoint-react-webpart && cd sharepoint-react-webpart

2. Установить дополнительный зависимости (sp-rest-proxy и concurrently):

  • sp-rest-proxy - библиотека ответственная за маршрутизацию запросов к API SharePoint. Подробнее о прокси.
  • concurrently - необходим для организации параллельного запуска нескольких npm задач одной командой в одной терминальной сессии (удобно же!).
npm install sp-rest-proxy concurrently --save-dev

3. Добавить скрипты в package.json:

{
  "scripts": {
    ...
    "proxy": "node ./api-server.js",
    "startServers": "concurrently --kill-others "npm run proxy" "npm run start""
    ...
  }
}

Названия скриптов могут быть любые, как больше нравится. npm run start - это штатный запуск режима разработки с локальным веб-сервером. node ./api-server.js запускает процесс sp-rest-proxy сервера. О самом скрипте чуть позже.

4. Добавить настройку проксирования CRA в package.json:

{
  "proxy": "http://localhost:8081"
}

Указанный адрес и порт должены соответстовать тем, что указаны в настройках сервера sp-rest-proxy. Прокси из состава CRA - это возможность Webpack Dev Server, которая так же проксирует запросы через свой бэкенд, чтобы не было проблем с CORS. В отличии от штатного прокси фишка sp-rest-proxy заключается в том, что он умеет авторизоваться в SharePoint.

В итоге Package.json должен выглядеть примерно так (на версию зависимостей лучше не образать внимание):

5. Создать JS скрипт для старта прокси ./api-server.js:

const RestProxy = require('sp-rest-proxy');

const settings = {
  port: 8081
};

const restProxy = new RestProxy(settings);
restProxy.serve();

У sp-rest-proxy довольно много настроек, которые можно переопределить, но значения по умолчанию в большинстве стучаев подойдут.

6. Подключить sp-rest-proxy к SharePoint:

6.1. Запусть:

npm run proxy

6.2. указать параметры подключения к SharePoint в вопросах мастера подключения.

По умолчанию, параметры подключени сохраняются в ./config/private.json. Файл подключения лучше исключать из репозитория, добавляя config/private.json в .gitignore. Таким образом ваши параметры случайно не улетят, однако, пароль хешируется таким образом, что его расшифровка возможна только на той же машине, где производилось хеширование.

6.3. Проверить, что подключение корректное открыв http://localhost:8081 и выполнив любой запрос к API во встроенном REST клиенте, например /_api/web. Если все хорошо, то вы увидете JSON ответ от API.

Остановить sp-rest-proxy, Ctrl+C в консоли.

7. Запуск режима разработки:

npm run startServers

Теперь при запуске разработки, в открывающемся приложении CRA можно отправлять запросы на /_api, как будто вы находитесь на странице SharePoint, при этом запросы минуя проблемы с CORS и аутентификации направляются к SharePoint с живой объектной моделью. Не надо делать миллион зачастую бесполезных mock'ов с данными, можно проверять не только чтение, но и создание и запись данных. А самое главное, сразу после сохранения кода видеть результат без необходимости публиковать что либо в SharePoint.

Например, зайдем на страницу локально запущенного приложения http://localhost:3000 и в консоли браузера запустим:

fetch(`/_api/web`, {
    accept: 'application/json;odata=verbose',
})
  .then(r => r.json())
  .then(console.log)
  .catch(console.log);

Вуаля, вы только что получили данные из SharePoint с локальной страницы. Удачной разработки!


Опубликовано: 22.10.2018
Автор: Андрей Кольтяков