Сниппет, расширение для VSCode и CLI. Часть 1

Доброго времени суток, друзья!

В процессе разработки Современного стартового HTML-шаблона я задумался о расширении возможностей его использования. На тот момент варианты его применения ограничивались клонированием репозитория и скачиванием архива. Так появились HTML-сниппет и расширение для Microsoft Visual Studio Code — HTML Template, а также интерфейс командной строки — create-modern-template. Конечно, указанные инструменты далеки от совершенства и я буду их дорабатывать по мере сил и возможностей. Однако, в процессе их создания я узнал несколько интересных вещей, которыми и хочу с вами поделиться.

В этой части мы рассмотрим сниппет и расширение, а CLI — в следующей.

Если вас интересует лишь исходный код, вот ссылка на репозиторий.

Сниппет (Snippet)

Что такое сниппет? Если коротко, сниппет — это заготовка, которую использует редактор для автозаполнения (автодополнения кода).

В VSCode встроен Emmet (официальный сайт, Emmet in Visual Studio Code), который использует многочисленные HTML, CSS и JS-сниппеты для помощи в написании кода. Набираем в редакторе (в .html) !, нажимаем Tab или Enter, получаем готовую html5-разметку. Набираем nav>ul>li*3>a.link>img, нажимаем Tab, получаем:

<nav>     <ul>       <li><a href="" class="link"><img src="" alt=""></a></li>       <li><a href="" class="link"><img src="" alt=""></a></li>       <li><a href="" class="link"><img src="" alt=""></a></li>     </ul>   </nav> 

и т.д.

Кроме встроенных, VSCode предусматривает возможность использования пользовательских сниппетов. Для их создания необходимо перейти в File -> Preferences -> User Snippets (или нажать на кнопку Manage в левом нижнем углу и выбрать User Snippets). Настройки для каждого языка хранятся в соответствующем JSON-файле (для HTML в html.json, для JavaScript в javascript.json и т.д.).

Потренируемся создавать JS-сниппеты. Находим файл javascript.json и открываем его.

Видим комментарии, кратко описывающие правила создания сниппетов. Более подробную информацию о создании пользовательских сниппетов в VSCode можно найти здесь.

Начнем с чего-нибудь простого. Создадим сниппет для console.log(). Вот как он выглядит:

"Print to console": {   "prefix": "log",   "body": "console.log($0)",   "description": "Create console.log()" }, 

• Print to console — ключ объекта, название сниппета (обязательно)
• prefix — сокращение для сниппета (обязательно)
• body — сам сниппет (обязательно)
• $число — положение курсора после создания сниппета; $1 — первое положение, $2 — второе и т.д., $0 — последнее положение (опционально)
• description — описание сниппета (опционально)

Сохраняем файл. Набираем log в скрипте, нажимаем Tab или Enter, получаем console.log() с курсором между скобками.

Создадим сниппет для цикла for-of:

"For-of loop": {   "prefix": "fo",   "body": [     "for (const ${1:item} of ${2:arr}) {",     "\t$0",     "}"   ] }, 

• Сниппеты, состоящие из нескольких строк, создаются с помощью массива
• ${число: значение}; ${1:item} означает первое положение курсора со значением item по умолчанию; данное значение выделяется после создания сниппета, а также после перехода к следующему положению курсора для быстрого редактирования
• \t — один отступ (величина оступа определяется соответствующими настройками редактора или, как в моем случае, расширения Prettier), \t\t — два отступа и т.д.

Набираем в скрипте fo, нажимаем Tab или Enter, получаем:

for (const item of arr) {  } 

с выделенным item. Нажимаем Tab, выделяется arr. Еще раз нажимаем Tab, переходим на вторую строку.

Вот еще несколько примеров:

"For-in loop": {   "prefix": "fi",   "body": [     "for (const ${1:key} in ${2:obj}) {",     "\t$0",     "}"   ] }, "Get one element": {   "prefix": "qs",   "body": "const $1 = ${2:document}.querySelector('$0')" }, "Get all elements": {   "prefix": "qsa",   "body": "const $1 = [...${2:document}.querySelectorAll('$0')]" }, "Add listener": {   "prefix": "al",   "body": [     "${1:document}.addEventListener('${2:click}', (${3:{ target }}) => {",     "\t$0",     "})"   ] }, "Async function": {   "prefix": "af",   "body": [     "const $1 = async ($2) => {",     "\ttry {",     "\t\tconst response = await fetch($3)",     "\t\tconst data = await res.json()",     "\t\t$0",     "\t} catch (err) {",     "\t\tconsole.error(err)",     "\t}",     "}"   ] } 

HTML-сниппеты строятся по такому же принципу. Вот как выглядит HTML Template:

{   "HTML Template": {     "prefix": "html",     "body": [       "<!DOCTYPE html>",       "<html",       "\tlang='en'",       "\tdir='ltr'",       "\titemscope",       "\titemtype='https://schema.org/WebPage'",       "\tprefix='og: http://ogp.me/ns#'",       ">",       "\t<head>",       "\t\t<meta charset='UTF-8' />",       "\t\t<meta name='viewport' content='width=device-width, initial-scale=1' />",       "",       "\t\t<title>$1</title>",       "",       "\t\t<meta name='referrer' content='origin' />",       "\t\t<link rel='canonical' href='$0' />",       "\t\t<link rel='icon' type='image/png' href='./icons/64x64.png' />",       "\t\t<link rel='manifest' href='./manifest.json' />",       "",       "\t\t<!-- Security -->",       "\t\t<meta http-equiv='X-Content-Type-Options' content='nosniff' />",       "\t\t<meta http-equiv='X-XSS-Protection' content='1; mode=block' />",       "",       "\t\t<meta name='author' content='$3' />",       "\t\t<meta name='description' content='$2' />",       "\t\t<meta name='keywords' content='$4' />",       "",       "\t\t<meta itemprop='name' content='$1' />",       "\t\t<meta itemprop='description' content='$2' />",       "\t\t<meta itemprop='image' content='./icons/128x128.png' />",       "",       "\t\t<!-- Microsoft -->",       "\t\t<meta http-equiv='x-ua-compatible' content='ie=edge' />",       "\t\t<meta name='application-name' content='$1' />",       "\t\t<meta name='msapplication-tooltip' content='$2' />",       "\t\t<meta name='msapplication-starturl' content='/' />",       "\t\t<meta name='msapplication-config' content='browserconfig.xml' />",       "",       "\t\t<!-- Facebook -->",       "\t\t<meta property='og:type' content='website' />",       "\t\t<meta property='og:url' content='$0' />",       "\t\t<meta property='og:title' content='$1' />",       "\t\t<meta property='og:image' content='./icons/256x256.png' />",       "\t\t<meta property='og:site_name' content='$1' />",       "\t\t<meta property='og:description' content='$2' />",       "\t\t<meta property='og:locale' content='en_US' />",       "",       "\t\t<!-- Twitter -->",       "\t\t<meta name='twitter:title' content='$1' />",       "\t\t<meta name='twitter:description' content='$2' />",       "\t\t<meta name='twitter:url' content='$0' />",       "\t\t<meta name='twitter:image' content='./icons/128x128.png' />",       "",       "\t\t<!-- IOS -->",       "\t\t<meta name='apple-mobile-web-app-title' content='$1' />",       "\t\t<meta name='apple-mobile-web-app-capable' content='yes' />",       "\t\t<meta name='apple-mobile-web-app-status-bar-style' content='#222' />",       "\t\t<link rel='apple-touch-icon' href='./icons/256x256.png' />",       "",       "\t\t<!-- Android -->",       "\t\t<meta name='theme-color' content='#eee' />",       "\t\t<meta name='mobile-web-app-capable' content='yes' />",       "",       "\t\t<!-- Google Verification Tag -->",       "",       "\t\t<!-- Global site tag (gtag.js) - Google Analytics -->",       "",       "\t\t<!-- Global site tag (gtag.js) - Google Analytics -->",       "",       "\t\t<!-- Yandex Verification Tag -->",       "",       "\t\t<!-- Yandex.Metrika counter -->",       "",       "\t\t<!-- Mail Verification Tag -->",       "",       "\t\t<!-- JSON-LD -->",       "\t\t<script type='application/ld+json'>",       "\t\t\t{",       "\t\t\t\t'@context': 'http://schema.org/',",       "\t\t\t\t'@type': 'WebPage',",       "\t\t\t\t'name': '$1',",       "\t\t\t\t'image': [",       "\t\t\t\t\t'$0icons/512x512.png'",       "\t\t\t\t],",       "\t\t\t\t'author': {",       "\t\t\t\t\t'@type': 'Person',",       "\t\t\t\t\t'name': '$3'",       "\t\t\t\t},",       "\t\t\t\t'datePublished': '2020-11-20',",       "\t\t\t\t'description': '$2',",       "\t\t\t\t'keywords': '$4'",       "\t\t\t}",       "\t\t</script>",       "",       "\t\t<!-- Google Fonts -->",       "",       "\t\t<style>",       "\t\t\t/* Critical CSS */",       "\t\t</style>",       "",       "\t\t<link rel='preload' href='./css/style.css' as='style'>",       "\t\t<link rel='stylesheet' href='./css/style.css' />",       "",       "<link rel='preload' href='./script.js' as='script'>",       "\t</head>",       "\t<body>",       "\t\t<!-- HTML5 -->",       "\t\t<header>",       "\t\t\t<h1>$1</h1>",       "\t\t\t<nav>",       "\t\t\t\t<a href='#' target='_blank' rel='noopener'>Link 1</a>",       "\t\t\t\t<a href='#' target='_blank' rel='noopener'>Link 2</a>",       "\t\t\t</nav>",       "\t\t</header>",       "",       "\t\t<main></main>",       "",       "\t\t<footer>",       "\t\t\t<p>© 2020. All rights reserved</p>",       "\t\t</footer>",       "",       "\t\t<script src='./script.js' type='module'></script>",       "\t</body>",       "</html>"     ],     "description": "Create Modern HTML Template"   } } 

Набираем html, нажимаем Tab или Enter, получаем разметку. Положения курсора определены в следующем порядке: название приложения (title), описание (description), автор (author), ключевые слова (keywords), адрес (url).

Расширение (Extension)

На сайте VSCode имеется отличная документация по созданию расширений.

Мы создадим два варианта расширения: в форме сниппетов и в форме CLI. Второй вариант опубликуем в Visual Studio Marketplace.

Примеры расширений в форме сниппетов:

• JavaScript (ES6) code snippets
• ES7 React/Redux/GraphQL/React-Native snippets
• Vue VSCode Snippets

Расширения в форме CLI менее популярны, вероятно, по той причине, что существуют «настоящие» CLI.

Расширение в форме сниппетов

Для разработки расширений для VSCode, нам, кроме Node.js и Git, потребуется еще парочка библиотек, точнее, одна библиотека и плагин, а именно: yeoman и generator-code. Устанавливаем их глобально:

npm i -g yo generator-code // или yarn global add yo generator-code 

Выполняем команду yo code, выбираем New Code Snippets, отвечаем на вопросы.

Осталось скопировать созданный нами ранее HTML-сниппет в файл snippets/snippets.code-snippets (файлы сниппетов также могут иметь расширение json), отредактировать package.json и README.md, и можно публиковать расширение в маркетплейсе. Как видите, все очень просто. Слишком просто, подумал я, и решил создать расширение в форме CLI.

Расширение в форме CLI

Снова выполняем команду yo code. На этот раз выбираем New Extension (TypeScript) (не бойтесь, TypeScript в нашем коде почти не будет, а там, где будет, я дам необходимые разъяснения), отвечаем на вопросы.

Для того, чтобы убедиться в работоспособности расширения, открываем проект в редакторе:

cd htmltemplate code . 

Нажимаем F5 или на кнопку Run (Ctrl/Cmd+Shift+D) слева и кнопку Start Debugging сверху. Иногда при запуске можно получить ошибку. В этом случае отменяем запуск (Cancel) и повторяем процедуру.

В открывшемся редакторе нажимаем View -> Command Palette (Ctrl/Cmd+Shift+P), набираем hello и выбираем Hello World.

Получаем информационное сообщение от VSCode и соответствующее сообщение (поздравление) в консоли.

Из всех файлов, имеющихся в проекте, нас интересуют package.json и src/extension.ts. Директорию src/test и файл vsc-extension-quickstart.md можно удалить.

Заглянем в extension.ts (комментарии удалены для удобочитаемости):

// импорт функционала VSCode import * as vscode from 'vscode'  // функция, вызываемая при активации расширения export function activate(context: vscode.ExtensionContext) {   // сообщение, выводимое в консоль редактора,   // в котором запущена отладка расширения   console.log('Congratulations, your extension "htmltemplate" is now active!')    // функционал расширения   // команда - это свойство расширения   // htmltemplate - название расширения   // helloWorld - название команды   let disposable = vscode.commands.registerCommand(     'htmltemplate.helloWorld',     () => {       // информационное сообщение, отображаемое в редакторе       // при успешном выполнении команды       vscode.window.showInformationMessage('Hello World from htmltemplate!')     }   )    // регистрация команды   // судя по всему, здесь реализован паттерн проектирования "Подписка/Уведомление",   // один из вариантов паттерна "Наблюдатель"   context.subscriptions.push(disposable) }  // функция, вызываемая при деактивации расширения export function deactivate() {} 

Важный момент: ‘расширение.команда’ в extension.ts должно совпадать со значениями полей activationEvents и command в package.json:

"activationEvents": [   "onCommand:htmltemplate.helloWorld" ], "contributes": {   "commands": [     {       "command": "htmltemplate.helloWorld",       "title": "Hello World"     }   ] }, 

• commands — список команд
• activationEvents — функции, вызываемые при выполнении команд

Приступаем к разработке расширения.

Мы хотим, чтобы наше расширение по функционалу напоминало create-react-app или vue-cli, т.е. по команде create создавало проект, содержащий все необходимые файлы, в целевой директории.

Для начала отредактируем package.json:

"displayName": "HTML Template", "activationEvents": [   "onCommand:htmltemplate.create" ], "contributes": {   "commands": [     {       "command": "htmltemplate.create",       "title": "Create Template"     }   ] }, 

Создаем директорию src/components для хранения файлов проекта, которые будут копироваться в целевую директорию.

Создаем файлы проекта в виде ES6-модулей (VSCode по умолчанию использует ES6-модули (export/import), но поддерживает и CommonJS-модули (module.exports/require)): index.html.js, css/style.css.js, script.js и т.д. Содержимое файлов экспортируется по умолчанию:

// index.html.js export default ` <!DOCTYPE html> <html   lang="en"   dir="ltr"   itemscope   itemtype="https://schema.org/WebPage"   prefix="og: http://ogp.me/ns#" >   ... </html> ` 

Обратите внимание, что при таком подходе все изображения (в нашем случае, иконки) должны быть закодированы в Base64: вот один из подходящих онлайн-инструментов. Наличие строки «data:image/png;base64,» в начале преобразованного файла принципиального значение не имеет.

Для копирования (записи) файлов мы будем использовать fs-extra. Метод outputFile данной библиотеки делает томе самое, что и встроенный Node.js-метод writeFile, но также создает директорию для записываемого файла при ее отсутствии: например, если мы указали создать css/style.css, а директории css не существует, outputFile создаст ее и запишет туда style.css (writeFile при отсутствии директории выбросит исключение).

Файл extension.ts выглядит следующим образом:

import * as vscode from 'vscode' // импорт библиотеки fs-extra const fs = require('fs-extra') const path = require('path')  // импорт файлов проекта, точнее, содержимого этих файлов import indexHTML from './components/index.html.js' import styleCSS from './components/css/style.css.js' import scriptJS from './components/script.js' import icon64 from './components/icons/icon64.js' // ...  export function activate(context: vscode.ExtensionContext) {   console.log('Congratulations, your extension "htmltemplate" is now active!')    let disposable = vscode.commands.registerCommand(     'htmltemplate.create',     () => {       // мы хотим, чтобы файлы проекта хранились в директории html-template       // filename: string указывает TypeScript-компилятору,       // что типом аргумента, передаваемого функции,       // должна быть строка       const folder = (filename: string) =>         path.join(vscode.workspace.rootPath, `html-template/${filename}`)        // массив с контентом файлов       // files: string[] означает, что значением переменной files является массив строк       const files: string[] = [         indexHTML,         styleCSS,         scriptJS,         icon64,         ...       ]        // массив с названиями файлов       // обратите внимание, что индексы контента и названий файлов должны совпадать       const fileNames: string[] = [         'index.html',         'css/style.css',         'script.js',         'server.js',         'icons/64x64.png',         ...       ]        ;(async () => {         try {           // перебираем массив с контентом           for (let i = 0; i < files.length; i++) {              // метод outputFile принимает два обязательных и один опциональный параметр:             // путь к файлу (его название), содержимое файла и кодировку (по умолчанию UTF-8)              // если название файла включает png,             // значит, мы имеем дело с Base64-изображением:             // указываем соответствующую кодировку             if (fileNames[i].includes('png')) {               await fs.outputFile(folder(fileNames[i]), files[i], 'base64')             // иначе, используем кодировку по умолчанию             } else {               await fs.outputFile(folder(fileNames[i]), files[i])             }           }            // информационное сообщение об успехе операции           return vscode.window.showInformationMessage(             'All files created successfully'           )         } catch {           // сообщение об ошибке           return vscode.window.showErrorMessage('Failed to create files')         }       })()     }   )    context.subscriptions.push(disposable) }  export function deactivate() {} 

Для того, чтобы TypeScript не обращал внимания на отсутствие типов импортируемых файлов-модулей, создадим src/global.d.ts следующего содержания:

declare module '*' 

Протестируем расширение. Открываем его в редакторе:

cd htmltemplate code . 

Запускаем отладку (F5). Переходим в целевую директорию (test-dir, например) и выполняем команду create в Command Palette.

Получаем информационное сообщение об успешном создании файлов. Ура!

Публикация расширения в Visual Studio Marketplace

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

• Создать аккаунт в маркетплейсе (запомните значение поля publisher)
• Глобально установить библиотеку vsce

Редактируем package.json:

{   "name": "htmltemplate",   "displayName": "HTML Template",   "description": "Modern HTML Starter Template",   "version": "1.0.0",   "publisher": "puslisher-name",   "license": "MIT",   "keywords": [     "html",     "html5",     "css",     "css3",     "javascript",     "js"   ],   "icon": "build/128x128.png",   "author": {     "name": "Author Name @githubusername"   },   "repository": {     "type": "git",     "url": "https://github.com/username/dirname"   },   "engines": {     "vscode": "^1.51.0"   },   "categories": [     "Snippets"   ],   "activationEvents": [     "onCommand:htmltemplate.create"   ],   "main": "./dist/extension.js",   "contributes": {     "commands": [       {         "command": "htmltemplate.create",         "title": "Create Template"       }     ]   },   ... } 

Редактируем README.md.

Выполняем команду vsce package в директории расширения для создания публикуемого пакета с расширением vsix. Получаем файл htmltemplate-1.0.0.vsix.

На странице управления расширениями маркетплейса нажимаем кнопку New extension и выбираем Visual Studio Code. Переносим или загружаем в модальное окно VSIX-файл. Ждем завершения проверки.

После того, как рядом с номером версии появилась зеленая галочка, расширение становится доступным для установки в VSCode.

Для обновления расширения необходимо изменить номер версии в package.json, сгенерировать VSIX-файл и загрузить его в маркетплейс, нажав на кнопку More actions и выбрав Update.

Как видите, в создании и публикации расширений для VSCode нет ничего сверхестественного. На этом позвольте откланяться.

В следующей части мы создадим полноценный интерфейс командной строки сначала с помощью фреймворка от Heroku — oclif, затем без него. Наш Node.js-CLI будет сильно отличаться от расширения, в нем будет присутствовать некоторая визуализация, возможность опциональной инициализации git и установки зависимостей.

Надеюсь, вы нашли для себя что-нибудь интересное. Благодарю за внимание.