Streamline your workflow by effortlessly unpacking folders of templates.

0A. Your first Boilerplate

We start by creating a new template in our workspace. You'll be able to put anything in the src folder once it's created.

Open the Command Palette (Cmd+Shift+P)
Find > ⎖ Boilerplate!: Create new boilerplate...
Select $WORKSPACE/.vscode/templates
Type "My First Extension"

The template includes a src/example.txt that displays some available variables and how to use them. We explore this further down below in 2. Configuration.

0B. Import from Gist

If you've found a public gist you'd like to use, you can do the following:

Open Command Palette(Cmd+Shift+P) and find > ⎖ Boilerplate!: Import from gist...
Select the folder you'd like to save it to (e.g. home vs workspace)
Enter a name for the boilerplate
Paste the full URL or Gist ID into the prompt

It will fetch and download files from the public gist into the folder/name you've specified.

Here's a sample gist you can try that includes a few dot files such as .gitignore, .editorconfig, etc.

Usage

You can unpack a boilerplate directly to the root of your project using the Command Panel or you can unpack into a specific directory by right clicking and using the context menu.

Right click a folder in the Explorer
Select ⎖ Boilerplate!: Generate here...
Choose a boilerplate
Fill in required inputs (optional)

2. Configuration

The files in your boilerplate can evaluate variables, execute code, and apply user input to filenames. There are several types of variables available inside your templates.

Variables defined in your Code settings
Variables defined in process.env
A local package.json file (if available)
User defined input (asked by plugin)
Custom in-template contexts

General usage

Basic variables can be applied in the following ways:

${foo}
${env.USER}
${package.version}

User-defined input variables (as asked by the plugin) are namespaced under input. These would show up if you named a file {filename}.json or similar.

${input.filename}

We automatically include the environment variables and the nearest package.json file we can find.

Note: We start looking for a package.json in the path you've selected and search upwards for the nearest one. This allows you to have multiple projects open in a workspace but still use the most accurate manifest.

Custom Variables

Hardcoded variables with no special wrappings. You can add these to your User Settings.

"global-boilerplate.variables": {
	"${lorem}": "Lorem ipsum sit amet dolor.",
	"${my-variable}": "Hello World."
}

These would be accessible in your template via ${lorem} and ${my-variable}.

Evaluated Variables

You can include dynamic JavaScript evaluations by using a syntax like this:

${{ Date.now() }}

It will automatically return the value evaluated without need for a return statement. Within this context, all variables are available on a flattened object called variables, so an example from above would become:

variables.foo
variables.env_USER
variables.package_version

Note that multidimensional objects are flattened with an underscore rather than a period. These variables are accessible through the evaluation, so you could do something like:

// Input
User: ${{ variables.env_USER }}
Modified: ${{ variables.env_USER.toUpperCase() }}

// Output
User: polymermallard
Modified: POLYMERMALLARD

This can be combined into more complex situations like these:

${{
	const [major, minor, patch] = variables.package_version.split('.');

	`Major: ${major}\nMinor: ${minor}\nPatch: ${patch}`
}}

and

${{
	if (variables.package_author.indexOf('Kenefick') > -1) {
		`It's Matt.`
	}
	else {
		`It's someone else.`
	}
}}

Evaluated Contexts

The evaluated variables are powerful but sometimes you want to reuse them or perform more complex tasks. For that, we have a special syntax where you can define variables for future use.

Example:

{{{ variables.myVariable = 'This is my variable'.split(' ').join('-') }}}

${{ variables.myVariable }}

The generated output for this is:

Example:

This-is-my-variable

If any evaluated context fails, the subsequent contexts will NOT BE PROCESSED so make sure your code works.

3. Template Locations

You can specify where the extension searches for templates by defining paths in the Code settings file.

"global-boilerplate.templateDirectories": [
	".vscode/templates",
	"$HOME/VSCodeTemplates"
]

The following variables will be evaluated when searching the system:

~ = process.env.HOME
$HOME = process.env.HOME
$WORKSPACE= workspaceRoot

Release Notes

1.2.1

Boilerplate! renamed and refactored

0.2.1

Modify template to include src/ by default

0.2.0

Add dynamic filenames
Improve variables and add ability to set them
Add examples
Update README

0.1.0

Initial release

mattkenefick/vscode-file-template