This page covers the practical aspects of creating and using custom actions in Nordcraft.

Create an action

Live

To create a custom action:

1. 1

   Open the project sidebar by clicking the folder icon or using Cmd/Ctrl + K
2. 2

   Locate the Actions section, click the + button and enter a name
3. 3

   Add a short description for your action
4. 4

   Write your JavaScript code in the editor

Custom actions have a specific structure with an entry function that receives two parameters:

• args: Contains all arguments passed to the action
• ctx: Provides access to Nordcraft-specific functionality

The function can return a cleanup function that will be called when the component unmounts.

Configure arguments

Live

To add arguments to your action:

1. 1

   Click the + button in the Arguments section
2. 2

   Enter a name for the argument
3. 3

   Select the argument type from the dropdown ( String, Number, etc.)

In your code, access these arguments through the args parameter, using the names you defined.

Set up events

Live

To create events that your action can trigger:

1. 1

   Click the + button in the Events section
2. 2

   Enter a name for the event
3. 3

   Optionally provide example output to define the data structure

In your code, you can trigger events using the context object's triggerActionEvent method with the event name and data. When using the action in a workflow, you can then handle these events by adding actions to them.

When developing actions, keep these important considerations in mind:

• Client-side only: Actions only run in the browser, not during server-side rendering
• DOM access: Use ctx.root instead of document for DOM operations to ensure compatibility with Shadow DOM when components are exported as web components
• Asynchronous code: Actions can be asynchronous using async/await syntax or Promises
• Cleanup: Return a function from your action to automatically clean up resources when the component that triggered the action is unmounted (e.g. remove event listener)
• Error handling: Actions should handle errors gracefully to avoid breaking your application

Custom actions can be used just like built-in workflow actions. When creating a workflow, you can add your custom actions as nodes by selecting them from the Project Actions section. You can provide values for any arguments defined in the action and handle any events it might trigger.

Here is an example of a custom action in Norcraft. It demonstrates how the canvas-confetti library can be integrated to create a celebratory effect when triggered.