Custom Patterns

The true power of grit comes with the ability to write and share your own patterns. There are several ways to add custom patterns. Once configured in your repo, a custom pattern can be used through the CLI, the VSC extension, or the web app in the same way as any pattern from the Grit standard library.

The basic syntax for defining a pattern is to use the pattern keyword followed by the pattern name and a body.

The pattern keyword can be used to define a named pattern that is used by other patterns. Patterns can only be defined at the top level of a file - you can't nest pattern definitions.

pattern console_method_to_info($method) {
`console.$method($message)` => `console.info($message)`
}
console_method_to_info(method = `log`)

console.log('Hello, world!');
console.warn('Can you hear me?');

console.info('Hello, world!');
console.warn('Can you hear me?');

Pattern names must begin with a letter or an underscore, followed by any combination of alphanumeric characters and underscores.

Pattern parameter names can be omitted as long as arguments are provided in the same order as the parameters are defined. For example, the console_method_to_info pattern from above could be called like this:

pattern console_method_to_info($method) {
`console.$method($message)` => `console.info($message)`
}
console_method_to_info(`log`)

console.log('Hello, world!');
console.warn('Can you hear me?');

console.info('Hello, world!');
console.warn('Can you hear me?');

Patterns can be marked as private by including the private keyword before the pattern. Private patterns are not visible in the pattern list and are only meant to be used within a module's context.

private pattern this_pattern_is_hidden() {
  `console`
}

Any patterns defined in .grit files within a .grit/patterns folder at the root of your repo will be automatically loaded for use within your repo.

The filename does not matter, so you can organize them however you want within that directory. You can also use subdirectories inside .grit/patterns to organize your patterns.

For example, place this file at .grit/patterns/example.grit:

pattern replace_console_log() {
  `console.log($args)` => `console.error($args)`
}

If you prefer to inline pattern definitions with other Grit config settings, custom patterns can be included in grit.yaml configuration files. For more information, see the config guide.

Patterns can be stored in *.md files within a .grit/patterns folder at the root of your repo, including in subdirectories.

The name of the file is used as the name of the pattern, and the first fenced code block in the file is used as the pattern body.

Here is an example of a markdown pattern file:

# Remove console.log

Remove console.log in production code.

```grit
`console.log($_)` => .
```

This pattern can then be called as "remove_console_log" in other patterns. You can also include additional pattern definitions in the code block—only the root pattern gets exported.

You can see more examples of valid markdown pattern configs in the Grit standard library.

Additional pattern metadata can be configured as YAML in the frontmatter of the markdown file, delineated between --- lines at the start of the document. This configuration follows the same rules as the pattern schema in the config guide, though the name and body fields are ignored.