Tutorial: Create Your First Snippet

// Step-by-step guide to create, test, and install your first snippet

What is a Snippet?

A snippet is a reusable piece of code, template, or directory structure that you can share and install across projects. Snippets support dynamic variable substitution using Handlebars templates, allowing you to create flexible, configurable code generation.

With mir, you can:

- Create reusable code templates with variables
- Share snippets with your team or the community
- Install snippets from local or remote registries
- Customize snippets through interactive prompts

Installation

Install mir globally or use it with npx:

// terminal

# Install globally
$ npm install -g @tbsten/mir

# Or use directly with npx
$ npx @tbsten/mir --help

You're now ready to create your first snippet!

Initialize Your Project

Start by initializing a new mir project. This creates the necessary directory structure and sample configuration files.

// terminal

$ mir init

This will create a .mir/ directory with:

- snippets/ directory for your snippets
- mirconfig.yaml with registry settings
- A sample hello-world snippet
- README.md with quick start guide

Create a New Snippet

Create a new snippet template. Replace my-snippet with your snippet name.

// terminal

$ mir create my-snippet

This command creates:

- .mir/snippets/my-snippet.yaml (snippet definition)
- .mir/snippets/my-snippet/ (template directory)

Edit the YAML Definition

Open .mir/snippets/my-snippet.yaml and define your snippet metadata and variables.

// .mir/snippets/my-snippet.yaml

name: my-snippet
version: "1.0.0"
description: "A description of what this snippet does"

variables:
  - name: projectName
    description: "Name of the project"
    default: "my-project"

  - name: authorName
    description: "Your name"
    default: "John Doe"

files:
  - path: "src/index.js"
  - path: "package.json"

Key fields:

- name: Unique identifier for your snippet
- variables: Input fields for users
- files: Template files to generate

Create Template Files

Add template files to the my-snippet/ directory. Use Handlebars syntax to reference variables.

// .mir/snippets/my-snippet/src/index.js

// Created for {{projectName}}
// Author: {{authorName}}

export function greet(name) {
  return `Hello, ${name}! Welcome to {{projectName}}.`;
}

// Main execution
console.log(greet('World'));

// .mir/snippets/my-snippet/package.json

{
  "name": "{{projectName}}",
  "version": "1.0.0",
  "description": "Generated by mir",
  "main": "src/index.js",
  "author": "{{authorName}}",
  "license": "MIT"
}

Handlebars variables like {{projectName}} will be replaced with user input. Learn more in the Template Syntax guide.

Publish to Local Registry

Once your snippet is ready, publish it to your local registry.

// terminal

$ mir publish my-snippet

This stores your snippet in ~/.mir/registry/ where you (and others) can install it.

Test Installation

Verify that your snippet works by installing it in a test directory.

// terminal

$ cd /tmp/test-my-snippet
$ mir install my-snippet
# Follow the interactive prompts to enter variables

After installation, verify that:

- All files are generated correctly
- Variables are properly substituted
- The generated code matches your expectations

Next Steps

Congratulations! You've successfully created your first snippet. Here are some next steps:

- Share your snippet with others through a custom registry
- Learn advanced features in the Variables guide
- Explore Template Syntax for more Handlebars features
- Submit your snippet to the official registry

Frequently Asked Questions

Q: What's the difference between snippets and regular files?

Snippets are parameterized templates that generate customized output based on user input. While you could copy files manually, snippets automate this process with variable substitution, making them perfect for boilerplate code and repeated patterns.

Q: Can I use snippets in an existing project?

Yes! You can install snippets anywhere. mir will generate files in your current directory. Just navigate to the location where you want to install the snippet and run the install command.

Q: How do I create custom snippets for my team?

Use mir create <name> to create a snippet template. Edit the YAML definition and Handlebars template files, then publish with mir publish <name>. You can share snippets via a custom registry URL.

Q: Can I use a remote registry instead of the local one?

Yes! Set your registry URL in ~/.mir/mirconfig.yaml or pass it directly with the --registry flag. mir supports both local and remote registries.

Q: How do I use Handlebars in snippet templates?

Use {{variableName}} syntax in your template files. Check the Template Syntax guide for advanced features like conditionals and loops.

Q: What happens if I make a mistake in my snippet?

You can update your snippet by editing the YAML and template files, then republishing. Use mir publish --force to overwrite the existing version.

Tips for Better Snippets

- Keep variable names simple and descriptive
- Provide meaningful default values
- Include helpful comments in your templates
- Test your snippet with different variable values