Skip to content

Improve developer experience for plugin renaming #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
davewaring wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve developer experience for plugin renaming #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 88 additions & 0 deletions RENAME_CHECKLIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Plugin Rename Checklist

After cloning this template, use this checklist to rename everything for your plugin.

**Example:** Renaming to "MyAwesomePlugin" with module "MyAwesomeModule"

---

## Critical Rule

> **Plugin name and module name MUST be different!**
>
> - Bad: Plugin = "MyPlugin", Module = "MyPlugin"
> - Good: Plugin = "MyPlugin", Module = "MyPluginModule"
>
> BrainDrive can't distinguish between them if they're the same.

---

## Checklist

### 1. Folder Name
- [ ] Rename the cloned folder from `BrainDrive-PluginTemplate` to `MyAwesomePlugin`

### 2. package.json
- [ ] Update `name` to `"my-awesome-plugin"`
- [ ] Update `description` to describe your plugin

### 3. webpack.config.js (lines 7-9)
- [ ] Update `PLUGIN_NAME` to `"MyAwesomePlugin"`
- [ ] Update `PLUGIN_MODULE_NAME` to `"MyAwesomeModule"` (must differ from plugin!)
- [ ] Update `PLUGIN_PORT` to an available port (e.g., 3004)

### 4. Source Files
- [ ] Rename `src/PluginTemplate.tsx` to `src/MyAwesomePlugin.tsx`
- [ ] Rename `src/PluginTemplate.css` to `src/MyAwesomePlugin.css`

### 5. Inside Your Renamed .tsx File
- [ ] Update CSS import: `import './MyAwesomePlugin.css'`
- [ ] Update class name: `class MyAwesomePlugin extends React.Component`
- [ ] Update export: `export default MyAwesomePlugin`

### 6. src/index.tsx
- [ ] Update import: `import MyAwesomePlugin from './MyAwesomePlugin'`
- [ ] Update export: `export default MyAwesomePlugin`
- [ ] Update metadata object name and description
- [ ] Update JSX references in dev mode render

### 7. lifecycle_manager.py
In `plugin_data` (around line 101):
- [ ] Update `name` to `"MyAwesomePlugin"`
- [ ] Update `description`
- [ ] Update `scope` to `"MyAwesomePlugin"`
- [ ] Update `plugin_slug` to `"MyAwesomePlugin"`
- [ ] Update `source_url` to your GitHub repo
- [ ] Update `update_check_url` to your GitHub releases URL

In `module_data` (around line 129):
- [ ] Update `name` to `"MyAwesomeModule"` (DIFFERENT from plugin name!)
- [ ] Update `display_name`
- [ ] Update `description`

### 8. Optional: src/types.ts
- [ ] Rename `PluginTemplateProps` to `MyAwesomePluginProps`
- [ ] Rename `PluginTemplateState` to `MyAwesomePluginState`

---

## Quick Verification

After renaming, run:

```bash
npm run build
```

Check that `dist/remoteEntry.js` is created. If the build succeeds, your renaming is complete!

---

## Common Mistakes

| Mistake | Symptom | Fix |
|---------|---------|-----|
| Plugin and module have same name | Confusing errors, components don't load | Make module name different |
| Forgot to update import in index.tsx | "Module not found" error | Update import path |
| Forgot to update CSS import | Style errors or missing styles | Update CSS import path |
| Mismatched names in lifecycle_manager.py | Plugin doesn't appear in Page Builder | Ensure name, scope, slug match |
7 changes: 6 additions & 1 deletion lifecycle_manager.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,14 @@ def __init__(self, plugins_base_dir: str = None):
}

# TEMPLATE: Define module data - TODO: Customize for your plugin's modules
# ========================================================================
# CRITICAL: Module name MUST be DIFFERENT from plugin name!
# BAD: plugin name = "MyPlugin", module name = "MyPlugin" (won't work!)
# GOOD: plugin name = "MyPlugin", module name = "MyPluginModule"
# ========================================================================
self.module_data = [
{
"name": "PluginTemplateModule", # Must differ from plugin name
"name": "PluginTemplateModule", # MUST differ from plugin_data["name"] above!
"display_name": "Plugin Template", # TODO: Update display name
"description": "A template component for BrainDrive plugins", # TODO: Update description
"icon": "Puzzle", # TODO: Choose appropriate icon
Expand Down
10 changes: 7 additions & 3 deletions webpack.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,14 @@ const HtmlWebpackPlugin = require("html-webpack-plugin");
const { ModuleFederationPlugin } = require("webpack").container;
const deps = require("./package.json").dependencies;

// =============================================================================
// TEMPLATE: Customize these values for your plugin
const PLUGIN_NAME = "PluginTemplate"; // TODO: Change this to your plugin name
const PLUGIN_MODULE_NAME = "PluginTemplateModule"; // TODO: Change this to your module name (must match lifecycle_manager.py)
const PLUGIN_PORT = 3003; // TODO: Change this to an available port
// CRITICAL: PLUGIN_NAME and PLUGIN_MODULE_NAME must be DIFFERENT!
// See RENAME_CHECKLIST.md for complete renaming instructions
// =============================================================================
const PLUGIN_NAME = "PluginTemplate"; // TODO: Change to your plugin name
const PLUGIN_MODULE_NAME = "PluginTemplateModule"; // TODO: Change to your module name (MUST differ from PLUGIN_NAME!)
const PLUGIN_PORT = 3003; // TODO: Change to an available port

module.exports = {
mode: "development",
Expand Down