Lifecycle hooks

You can implement lifecycle hooks to automatically run an action, such as displaying a dialog or notification, when a user installs or updates your Snap.

Steps

1. Request permission to implement lifecycle hooks

Request the endowment:lifecycle-hooks permission. Add the following to your Snap's manifest file:

snap.manifest.json

"initialPermissions": {
  "endowment:lifecycle-hooks": {}
}

2. Run an action on installation

To run an action when a user installs your Snap, expose the onInstall entry point and implement the action. For example, you can use onInstall to perform any initialization that is required upon installation.

The following example displays an alert dialog upon installation:

JSX

index.tsx

import type { OnInstallHandler } from "@metamask/snaps-sdk";
import { Box, Heading, Text } from "@metamask/snaps-sdk/jsx";

export const onInstall: OnInstallHandler = async () => {
  await snap.request({
    method: "snap_dialog",
    params: {
      type: "alert",
      content: (
        <Box>
          <Heading>Installation successful</Heading>
          <Text>
            To use this Snap, visit the companion dapp at <a href="https://metamask.io">metamask.io</a>.
          </Text>
        </Box>
      ),
    },
  });
};

Functions

index.ts

import type { OnInstallHandler } from "@metamask/snaps-sdk"
import { heading, panel, text } from "@metamask/snaps-sdk"

export const onInstall: OnInstallHandler = async () => {
  await snap.request({
    method: "snap_dialog",
    params: {
      type: "alert",
      content: panel([
        heading("Installation successful"),
        text(
          "To use this Snap, visit the companion dapp at [metamask.io](https://metamask.io)."
        ),
      ]),
    },
  })
}

3. Run an action on update

To run an action when a user updates your Snap, expose the onUpdate entry point and implement the action. For example, you can use onUpdate to perform any migrations that are required upon update.

The following example displays an alert dialog upon update:

JSX

index.tsx

import type { OnUpdateHandler } from "@metamask/snaps-sdk";
import { Box, Heading, Text } from "@metamask/snaps-sdk/jsx";

export const onUpdate: OnUpdateHandler = async () => {
  await snap.request({
    method: "snap_dialog",
    params: {
      type: "alert",
      content: (
        <Box>
          <Heading>Update successful</Heading>
          <Text>New features added in this version:</Text>
          <Text>Added a dialog that appears when updating.</Text>
        </Box>
      ),
    },
  });
};

Functions

index.ts

import type { OnUpdateHandler } from "@metamask/snaps-sdk"
import { heading, panel, text } from "@metamask/snaps-sdk"

export const onUpdate: OnUpdateHandler = async () => {
  await snap.request({
    method: "snap_dialog",
    params: {
      type: "alert",
      content: panel([
        heading("Update successful"),
        text("New features added in this version:"),
        text("Added a dialog that appears when updating."),
      ]),
    },
  })
}

Example

See the @metamask/lifecycle-hooks-example-snap package for a full example of implementing lifecycle hooks.