Common Configuration Sections

metadata

The metadata section provides basic identifying information about the brick.

metadata:
  # The unique id for the brick. Must be lower-case and of one of the following forms:
  id: github/profile
  
  # The semantic version of the brick, cf. https://semver.org/
  version: 0.0.1
  
  # A unique name for the brick
  name: Github Profile Reader
  
  # A longer description for the brick
  description: Read information from a Github user profile

metadata.id

A brick's id is its unique id in the PixieBrix ecosystem. An id is lower-case with letters a-z. An id may also include hyphens. A brick's id can also include a collection namespace. Collections are used to namespace bricks that provide similar functionality, or applicable in similar contexts (e.g., websites)

Public bricks id structure:

• <name>
• <collection>/<name>

Individuals and teams can also select an identifier that they can use to namespace their bricks. These bricks can be shared with other teams, or published publicly.

Private/shared bricks id structure:

• <@organization>/<collection>/<name>: e.g., @pixiebrix/browser/open-tab
• <@organization>/<name>: e.g., @pixiebrix/get
• <@username>/<collection>/<name>
• <@username>/<name>

The @local namespace is reserved for bricks created locally in the extension, and not shared anywhere

metadata.version

The version of the brick. Bricks are expected to use semantic versioning

In the future, we plan to automatically detect semver violations by comparing input and output schemas. For example, the following changes would indicate a semantic change:

• Input: a required property is added
• Output: a property is removed, or a required output is made optional

isAvailable

The isAvailable entry specifies when the brick is available and can be run. The isAvailable section is used in the following kinds of bricks:

• Foundations (kind extensionPoint)
• Readers (kind reader)
• Services (kind service): determines which URLs the service is able to authenticate. The matchPatterns entry is tested against the API request URL.

isAvailable:
  
  # A match pattern or array of match patterns. The brick will be available if _any_ of the patterns match
  # If you want to match all URLs for a given domain, be sure to put a glob * at the end of the URL
  matchPatterns: https://github.com/*
  
  # This property does not apply to service configurations
  selectors: ".user-profile-sticky-bar"

isAvailable.matchPatterns

A match pattern or array of match patterns. The brick/service will be available if any of the patterns match.

For services, the match pattern is applied to the request URL. (i.e., as opposed to the URL where the bricks are being executed.)

For more examples of match patterns, see the Mozilla Developer Network documentation

isAvailable.selectors

Optionally provide one or more JQuery selectors that must be present on the page for the brick to be available.

For performance considerations of different selectors, see here: Optimize Selectors