# create-vk-mini-app

Пакет **create-vk-mini-app** предназначен для создания и развёртывания [мини-приложений ВКонтакте](https://dev.vk.ru/mini-apps/overview). С его помощью вы можете быстро создать проект мини-приложения с подключёнными библиотеками и инструментами, которые необходимы для работы на платформе ВКонтакте.

## Ключевые особенности

- Cборка с помощью [Vite](https://vitejs.dev/guide/).

- Автоматическое подключение и поддержка последних версий библиотек, необходимых для создания мини-приложений.

- Конфигурация проекта под различные задачи.

- Поддержка TypeScript и JavaScript.

- Интерактивный режим создания проекта.

- Бесплатный хостинг мини-приложения при помощи [vk-miniapps-deploy](https://dev.vk.ru/ru/mini-apps/development/hosting).

## Запуск

### yarn

```
yarn create @vkontakte/vk-mini-app [app-dir-name] [params]
```

### npm

```
npm init @vkontakte/vk-mini-app@latest [app-dir-name] -- [params]
```

> Обратите внимание на двойное тире перед списком параметров. Оно необходимо, это требование npm.

### npx

```
npx @vkontakte/create-vk-mini-app [app-dir-name] [params]
```

### Для Node.js < 18.0.0

Если вы используете более раннюю версию Node.js, чем 18.0.0, то вам нужен пакет create-vk-mini-app версии 1. Чтобы указать номер версии, введите `@1` после названия пакета.

```
npx @vkontakte/create-vk-mini-app@1 [app-dir-name] [options]
```

### Дальнейшие шаги

Команды, упомянутые выше, запускают скрипт создания приложения. Скрипт последовательно попросит вас указать следующие параметры:

- Имя папки для приложения. Если имя папки соответствует требованиям именования npm-пакетов, то это же имя будет указано как название проекта в `package.json`. Если имя папки не может быть использовано для именования пакета, скрипт попросит вас указать другое имя.

- Язык программирования: TypeScript или JavaScript.

- Структурные шаблоны — набор библиотек, которые будут включены в проект:

  - VKUI+Bridge+Router — рекомендуемый вариант для создания мини-приложений ВКонтакте.

  - VKUI+Bridge

  [Подробнее о шаблонах](#project-templates)

## Параметры командной строки

При запуске вы можете ввести следующие параметры командной строки, чтобы указать характеристики создаваемого приложения.

Все параметры необязательные.

<table>
<thead>
<th>Параметр</th>
<th>Описание</th>
</thead>
<tbody>
<tr>
<td><b>app-dir-name</b></td>
<td>Имя папки для создаваемого приложения.</td>
</tr>
<tr>
<td width="210px"><b>--projectName={name}</b></td>
<td>Имя проекта создаваемого приложения, которое будет указано в <code>package.json</code>.<br/>Используется в случае, когда имя папки не соответствует правилам именования npm-пакетов.</td>
</tr>
<tr>
<td><b>--typescript</b></td>
<td>Создаёт проект на TypeScript. Если этот параметр не указан, то скрипт попросит указать язык при создании приложения.</td>
</tr>
<tr>
<td><b>--template={name}</b><br/>или<br/><b>--t={name}</b></td>
<td>Структурный шаблон — набор библиотек, которые будут включены в приложение при создании. Возможные значения <code>{name}</code>: <ul><li>vkui-bridge-router</li><li>vkui-bridge</li></ul> </td>
</tr>
</tbody>
</table>

## Примеры командной строки

#### Пример 1

```
yarn create  @vkontakte/vk-mini-app mini-app --typescript --template=vkui-bridge-router
```

Создаст проект из структурного шаблона `VKUI+Bridge+Router` на TypeScript в подпапке `mini-app` текущей папки.

#### Пример 2

```
npm init  @vkontakte/vk-mini-app . -- --template=vkui-bridge
```

Создаст проект из структурного шаблона `VKUI+Bridge`. Скрипт запросит имя папки и язык программирования.

## <a id='project-templates'/> Структурные шаблоны

## <a id='project-templates'/> Структурные шаблоны

| Параметр                            | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <nobr>**vkui-bridge-router**</nobr> | Проект со следующими включёнными библиотеками: <ul><li>[VKUI](https://github.com/VKCOM/VKUI) — Библиотека React-компонентов для создания UI.</li><li>[VK Bridge](https://github.com/VKCOM/vk-bridge/) — Библиотека для взаимодействия с платформой ВКонтакте.</li><li>[vk-mini-apps-router](https://github.com/VKCOM/vk-mini-apps-router) — Библиотека маршрутизации.</li></ul>**Совет.** Мы рекомендуем именно этот вариант для создания мини-приложений.<br/><br/>В проект также подключены другие инструменты и пакеты, которые упрощают создание мини-приложений:<ul><li>vk-miniapps-deploy — размещение файлов мини-приложения на [хостинге ВКонтакте](https://dev.vk.ru/ru/mini-apps/development/hosting).</li><li>Eruda — консоль разработчика. Используется для отладки.</li><li>@vkontakte/icons — набор иконок.</li><li>Vite — сборка приложения.</li><li>ESLint — проверка синтаксиса и правил кодирования.</li><li>React и React-DOM — стандартные React-библиотеки.</li></ul> |
| **vkui-bridge**                     | Те же библиотеки и инструменты, что и при использовании **vkui-bridge-router**, за исключением библиотеки маршрутизации `vk-mini-apps-router`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Полезные ссылки

- [Документация VKUI](https://vkcom.github.io/VKUI/)

- [Документация vk-mini-apps-router](https://dev.ru/libraries/router)

- [Примеры мини-приложений](https://dev.vk.ru/mini-apps/examples)

- [Сообщество VK Mini Apps](https://vk.ru/vkappsdev) — сообщество разработчиков мини-приложений ВКонтакте

## Сотрудничество

Мы рады новым идеям и предложениям по улучшению библиотеки. Если вы хотите расширить примеры или улучшить интерфейс командной строки:

1. Сделайте ответвление (fork) репозитория.

2. Склонируйте репозиторий и установите зависимости, выполнив команду `yarn`.

3. Внесите изменения в код.

4. Выполните сборку с помощью команды `yarn run build`.

5. Установите изменённый пакет: `yarn link`.
   Запустите его, чтобы протестировать изменения: `create-vk-mini-app`.

6. Отправьте MR нам на проверку.