Bun Stimulus Plugin

https://github.com/yummyume/bun-stimulus-plugin
Admin
A Bun plugin that automatically registers Stimulus controllers from a specified directory, offering...
Tokens:1,335
Snippets:9
Trust Score:7.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Bun Stimulus Plugin with Package Managers

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Demonstrates how to install the bun-stimulus-plugin using various package managers supported by Bun, including npm, Yarn, PNPM, and Bun itself. This is a prerequisite for using the plugin in your project.

```shell
# npm
npm install -D bun-stimulus-plugin

# Yarn
yarn add -D bun-stimulus-plugin

# PNPM
pnpm add -D bun-stimulus-plugin

# Bun
bun add -D bun-stimulus-plugin
```

--------------------------------

### Configure Bun Stimulus Plugin for Directory-Based Controllers

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

This example shows how to configure the Bun Stimulus Plugin to prioritize directory names over file names for controller registration. It disables file-based controllers and specifies a glob pattern for matching directories containing a controller file.

```typescript
await Bun.build({
    // ...
    plugins: [
        // Default values
        bunStimulusPlugin({
            fileIdentifier: null, // Do not load controllers from files
            directoryIdentifier: '**/controller.{js,ts}', // Load controllers from directories containing a "controller.{js,ts}" file
        }),
    ],
});
```

--------------------------------

### Mix File and Directory Controller Loading - Bun

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Enables loading controllers from individual files and also from directories containing a specific controller file. This offers flexibility in how controllers are structured and registered within the project.

```typescript
await Bun.build({
    // ...
    plugins: [
        // Default values
        bunStimulusPlugin({
            fileIdentifier: '*.{js,ts}', // Load any non-nested file
            controllerSuffix: null, // Match any file name and do not strip any suffix
            directoryIdentifier: '**/controller.{js,ts}', // Load controllers from directories containing a "controller.{js,ts}" file
        }),
    ],
});
```

--------------------------------

### Import Stimulus Definitions in Application Code

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Illustrates how to import Stimulus controller definitions from a directory using the `stimulus:` prefix in your application code (`app.ts`). This syntax is enabled by the Bun Stimulus Plugin and is used to load controllers into the Stimulus application.

```typescript
import { Application } from '@hotwired/stimulus';
import definitions from 'stimulus:./controllers';

// Load the Stimulus application
const app = Application.start();

// Register the controllers in ./controllers
app.load(definitions);
```

--------------------------------

### Configure Bun Stimulus Plugin with Default Options

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

This snippet demonstrates how to initialize the Bun Stimulus Plugin with its default configuration during a Bun build. It shows the structure for passing an options object to the plugin, highlighting common settings like strict mode and controller suffixes.

```typescript
await Bun.build({
    // ...
    plugins: [
        // Default values
        bunStimulusPlugin({
            strict: true, // If false, ignore invalid paths (definitions will be empty)
            controllerSuffix: /(-|_ )controller.(js|ts|jsx|tsx)$/gi, // Only load controllers with this suffix (will be stripped from the controller's identifier)
            controllerDirectorySuffix: null, // Only load controllers from directories with this suffix (will be stripped from the controller's identifier)
            fileIdentifier: '**/*', // The glob pattern to use for controller files (set to null to ignore file-based controllers)
            directoryIdentifier: null, // The glob pattern to use for directories (set to null to ignore directory-based controllers)
            duplicateDefinitionHandling: 'ignore', // How to handle duplicate definitions
        }),
    ],
});
```

--------------------------------

### Integrate Bun Stimulus Plugin into Bun Build

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Shows how to import and use the `bunStimulusPlugin` within a Bun build script (`build.ts`). This enables the plugin's functionality during the build process, allowing for automatic Stimulus controller registration.

```typescript
import { bunStimulusPlugin } from 'bun-stimulus-plugin';

await Bun.build({
    // ...
    plugins: [bunStimulusPlugin()],
});
```

--------------------------------

### Load Controllers from Directories with Suffix - Bun

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Configures the plugin to load controllers from directories that have a specific suffix. The suffix is automatically stripped from the controller name. This is useful for organizing controllers within named subdirectories.

```typescript
await Bun.build({
    // ...
    plugins: [
        // Default values
        bunStimulusPlugin({
            fileIdentifier: null, // Do not load controllers from files
            directoryIdentifier: '**/controller.{js,ts}', // Load controllers from directories containing a "controller.{js,ts}" file
            controllerDirectorySuffix: /-controller$/gi, // Only load controllers from directories with this suffix
        }),
    ],
});
```

--------------------------------

### Configure Duplicate Controller Definition Handling - Bun

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Sets the strategy for managing duplicate controller definitions during the build process. Options include ignoring, replacing, or throwing an error upon detecting duplicates.

```typescript
await Bun.build({
    // ...
    plugins: [
        // Default values
        bunStimulusPlugin({
            duplicateDefinitionHandling: 'replace', // Replace the first definition with the last one found
        }),
    ],
});
```

--------------------------------

### Custom Duplicate Definition Handling Callback - Bun

Source: https://github.com/yummyume/bun-stimulus-plugin/blob/master/README.md

Provides a custom callback function to define specific logic for handling duplicate controller definitions. This allows for complex scenarios, such as prioritizing directory-based controllers over file-based ones.

```typescript
await Bun.build({
    // ...
    plugins: [
        // Default values
        bunStimulusPlugin({
            fileIdentifier: '*.{js,ts}',
            controllerSuffix: null,
            directoryIdentifier: '**/controller.{js,ts}',
            duplicateDefinitionHandling: (exisitingDefinition, duplicateDefinition) => {
                if (
                    !exisitingDefinition.path.endsWith('controller.ts') &&
                    duplicateDefinition.path.endsWith('controller.ts')
                ) {
                    // If the current definition is from a file controller and the duplicate is from a directory controller, replace the file controller with the directory controller
                    return 'replace';
                }

                // Otherwise, fail the build (you could also return 'ignore' to keep the first definition found)
                return 'error';
            },
        }),
    ],
});
```
Tokens:
Raw