Шаблон проекта web-расширения

Описание файлов проекта

1. copy-path.js - константы с именем расширения и параметрами сборки (в частности, путь, куда копировать файлы после сборки).
2. gulpfile.js - конфигурация сборки стилей для Gulp
3. package.json - файл конфигурации NPM. Содержит определение команд сборки, а также используемые npm-зависимости.
4. package-lock.json - файл, который автоматически генерируется NPM при выполнении команды npm install. Это служебный файл NPM, он необходим для того, чтобы зависимости всегда устанавливались в одной и той же последовательности.
5. rollup.config.js - файл конфигурации Rollup, который используется для сборки файлов скриптов в один бандл.
6. tsconfig.json - файл конфигурации TypeScript
7. node_modules - служебная папка NPM, которая появляется после выполнения команды npm install. Содержит npm-зависимости проекта, используемые в процессе сборки.
8. src - исходные файлы расширения

Необходимое ПО

• NodeJS v10.6+
• VSCode или любой другой редактор

Начало работы

1. Переименовать расширение. Допустим, новое имя будет MyWebExtension (заменить на уникальное имя своего расширения). Для этого:
   • Переименовать саму папку TemplateWebExtension на MyWebExtension
   • Открыть файл copy-path.js и заменить значение EXTENSION_NAME на MyWebExtension.
   • Проверить, что путь SITE_ROOT указывает на то место, куда должны копироваться файлы расширения после сборки. Может быть указан только относительный путь (относительно самого файла). Можно указать путь к папке Site самого Web-клиента, тогда дополнительно устанавливать расширение не потребуется.
2. Открыть командную строку в корне проекта, выполнить npm install. В результате появится папка node_modules со всеми необходимыми зависимостями.
3. В командной строке выполнить npm run build.

После выполнения команды по пути SITE_ROOT (из файла copy-path.js) будут подготовлены файлы и папки, которые необходимо скопировать в папку Site в установке Web-клиента. В частности:

• Файл скриптов (Content/Modules/MyWebExtension/extension.js).
• Файл стилей (Content/Modules/MyWebExtension/extension.css). Файлы в данной папке подключаются автоматически в алфавитном порядке.

Дальнейшая разработка

Новые исходные файлы следует добавлять в папку src. Структура поддиректорий в этой папке не имеет значения. Стили и скрипты могут находится рядом, или быть разнесены - это также неважно. Единственное что требуется - файл src/Index.ts должен прямо или косвенно импортировать все остальные файлы расширения. Под косвенным импортированием подразумевается что файл Index.ts импортирует файл A.ts, а файл A.ts в свою очередь импортирует B.ts (в этом случае импортировать B.ts в файле Index.ts не обязательно). Также рекомендуется в файле Index.ts располагать код по регистрации обработчиков событий в глобальной области видимости (в объекте window), регистрации контролов через controlFactory, сервисов и т.д. В противном случае в процессе сборки диррективы импорта будут проигнорированы как неиспользуемые.

Для редактирования файлов удобно использовать VSCode. Для этого достаточно открыть саму папку в редакторе, после чего все файлы будут доступны в дереве проекта. Можно также использовать Visual Studio аналогичным образом.

При использовании сущностей Web-клиента можно использовать функцию авто-импорта. Например, мы можем начать писать вызов функции publishAsGlobal, и VSCode автоматически предложит добавить импорт во всплывающем меню.

В процессе разработки можно однажды запустить команду (для этого удобно воспользоваться встроенным терминалом VSCode):

npm run watch

Данная команда начнет отслеживание изменений в исходных файлах, и при каждом изменении будет пересобирать расширение и копировать файлы в SITE_ROOT. В режиме отслеживания сборка осуществляется значительно быстрее.

Команда npm run build собирает скрипты в один бандл extension.js без сжатия и с включенным маппингом исходных файлов. То есть, в браузере исходные файлы будут отображаться в том же виде, в каком они есть в папке src, что удобно для отладки. При некорректной работе маппинга, можно отключить в браузере маппинг, и использовать в отладке сам файл extension.js (т.к. он не минифицирован).

В процессе сборки используется rollup и gulp, однако можно использовать любую другую систему сборки (webpack, parcel и т.д.). Единственное требование - необходимо использовать какую-либо систему javascript модулей, поддерживаемую SystemJS (amd, commonjs, system).

Обратите внимание, что файлы модулей устанавливаются в папку Site/Content/Modules/<НазваниеРешения>

Для сборки расширения в режиме production необходимо запустить команду:

npm run build:prod

Единственное ее отличие - результирующие файлы минифицируются.