Open for Discussion: Add-Ons POC

[ahaywood]

At Redwood, we want to create an ecosystem of Add Ons or Shareware for your project. These can be as "simple" a single helper component or as a complex as an entire application.

Imagine starting a new project, and running a couple of commands -- you have a blog and newsletter ready to go, enabling you to focus on the business logic, essential to your application.

Just like shadcn/ui places your component code directly within your application, a RWSDK Add On's code lives directly in your application, completely yours, ready to be customized.

I created a Loom Video, explaining the current POC:
https://www.loom.com/share/6939da219a024aa088a56e46fee9c701

Here's the generated addon.jsonc file referenced with the video:

// addon.jsonc
{
  "name": "suggest",
  "description": "suggest add-on for RWSDK",
  "version": "0.1.0",
  "routes": {
    "file": "routes.ts",
    "prefix": ""
  },
  "packages": [
    "@radix-ui"
  ],
  "env": [
    "RESEND_API_KEY"
  ],
  "shadcn": {
    "required": true,
    "components": [
      "button",
      "input",
      "separator",
      "badge",
      "alert-dialog",
      "dialog",
      "label",
      "textarea",
      "checkbox",
      "switch",
      "dropdown-menu"
    ]
  },
  "tailwindcss": {
    "required": true
  },
  "styles": {
    "source": "src/app/addons/suggest/styles.css",
    "injectInto": "src/app/styles.css", // project-wide styles file,
    "injectDirective": "@import './addons/suggest/styles.css';"
  },
  "postInstallMessage": "✅ suggest add-on installed successfully."
}

---

README for how the Generate addon.jsonc file works

This document explains the generateAddonConfig.mjs script, which automatically analyzes an addon's content and generates the addon.jsonc configuration file.

Overview

The generateAddonConfig.mjs script scans your addon's codebase to detect:

• Package dependencies
• Environment variables
• CSS files
• Route files
• ShadCN UI components

Based on this analysis, it generates an addon.jsonc file that describes your addon's requirements and configuration.

Usage

node src/scripts/generateAddonConfig.mjs <addon-name>

Where <addon-name> is the name of your addon (e.g., "suggest").

Generated Configuration

The script generates an addon.jsonc file with the following sections:

Basic Information

{
  "name": "your-addon-name",
  "description": "your-addon-name add-on for RWSDK",
  "version": "0.1.0"
}

Routes

If your addon includes a routes file (routes.ts, routes.tsx, routes.js, or routes.jsx), the script will detect it and add:

"routes": {
  "file": "routes.ts",
  "prefix": "/your-prefix"
}

The prefix is extracted from your routes file.

Packages

The script analyzes all JavaScript/TypeScript files to find external package dependencies:

"packages": [
  "package-name-1",
  "package-name-2"
]

Note: The script filters out common packages and those that are already part of RedwoodSDK.

Environment Variables

If your addon includes an env.example file, the script will extract environment variables:

"env": [
  "API_KEY",
  "SECRET_TOKEN"
]

Tailwind CSS

The script automatically detects if your addon requires Tailwind CSS:

"tailwindcss": {
  "required": true
}

Tailwind is detected as required if:

• Your addon uses ShadCN UI components (which always require Tailwind)
• Your CSS files contain @apply directives (which are Tailwind-specific)

ShadCN Components

The script detects ShadCN UI components used in your addon:

"shadcn": {
  "required": true,
  "components": [
    "button",
    "input",
    "dialog",
    "dropdown-menu"
  ]
}

ShadCN components are detected by analyzing:

• Import statements with paths containing components/ui/
• Import statements with paths containing @/components/ui/ or @/app/components/ui/
• Relative imports with ./components/ui/ or ../components/ui/
• Direct JSX usage of component names

Note: When ShadCN components are detected, Tailwind CSS is automatically marked as required.

Styles

If your addon includes CSS files, the script will add:

"styles": {
  "source": "src/app/addons/your-addon/styles.css",
  "injectInto": "src/app/styles.css",
  "injectDirective": "@import './addons/your-addon/styles.css';"
}

Post-Install Message

"postInstallMessage": "✅ your-addon add-on installed successfully."

Advanced Configuration

ShadCN Component Detection

The script detects ShadCN components by:

1. Checking if a components/ui directory exists in the project
2. Finding all available ShadCN components in that directory
3. Scanning all JS/TS files in your addon for imports of these components
4. Checking for direct JSX usage of these components

The script uses multiple detection methods to ensure it catches all component usages:

• Regular expression matching for import statements
• Line-by-line analysis for complex import patterns
• JSX element detection

Package Filtering

The script filters out unnecessary packages to keep your addon's dependencies minimal:

• Common packages already included in RedwoodSDK
• Packages that are part of the ShadCN UI ecosystem when ShadCN is detected

Troubleshooting

If your addon's configuration is not generated correctly:

1. Missing ShadCN Components: Make sure your imports use one of the supported path formats:

   • @/app/components/ui/component-name
   • @/components/ui/component-name
   • ./components/ui/component-name
   • ../components/ui/component-name

2. Missing Environment Variables: Check that your env.example file follows the format:

   VARIABLE_NAME=example_value
   

3. Missing Routes: Ensure your routes file is named correctly (routes.ts, routes.tsx, routes.js, or routes.jsx) and is in the addon's root directory.

4. Missing Packages: The script only detects non-relative imports. If a package is missing, check that it's imported using the standard import syntax.

Manually Editing the Configuration

After the script generates the addon.jsonc file, you can manually edit it to add or modify any configuration options that weren't automatically detected.

---

README for how the Install Add On works

This document explains the installAddon.mjs script, which automates the installation of RedwoodSDK addons into your project.

Overview

The installAddon.mjs script is a comprehensive tool that handles all aspects of installing an addon into your RedwoodSDK project, including:

• Copying addon files to the correct location
• Installing required dependencies
• Setting up environment variables
• Injecting CSS styles
• Adding routes to your application
• Setting up Prisma schema
• Installing ShadCN UI components

Usage

node src/scripts/installAddon.mjs install <addonName> [options]

Options

Option	Description
--repo <url>	Install from a GitHub repository
--source <path>	Full path to the addon directory (not its parent)
--dest <path>	Destination directory (defaults to src/app/addons)
--help	Display help message

Examples

Install from a local directory:

node src/scripts/installAddon.mjs install suggest --source /path/to/addons/suggest

Install from a GitHub repository:

node src/scripts/installAddon.mjs install suggest --repo https://github.com/username/repo/addons

Installation Process

The script performs the following steps during installation:

1. Parse the addon.jsonc File

The script reads the addon's configuration from its addon.jsonc file, which contains information about:

• Addon name and description
• Required packages
• Environment variables
• Routes configuration
• ShadCN UI components
• CSS styles
• Post-install message

2. Install Framework Dependencies

If the addon requires specific frameworks, the script will install them:

• Tailwind CSS: If tailwind: true is specified in the addon.jsonc
• ShadCN UI: If shadcn: true or shadcn: { required: true } is specified

3. Install ShadCN Components

If the addon uses ShadCN UI components, the script will:

1. Ensure ShadCN UI is installed in your project
2. Install each required component listed in the shadcn.components array

4. Install Package Dependencies

The script installs any packages listed in the packages array using pnpm add.

5. Set Up Environment Variables

For each environment variable listed in the env array, the script:

1. Checks if the variable already exists in your .env file
2. If not, adds the variable to your .env file (without a value)

6. Inject CSS Styles

If the addon includes CSS styles:

1. The script looks for the target styles file specified in styles.injectInto
2. Adds the import directive specified in styles.injectDirective
3. Ensures proper ordering with Tailwind and ShadCN imports if needed

7. Add Routes

If the addon includes routes:

1. Adds an import statement for the routes file to your worker.tsx
2. Adds the routes to your application's render array
3. Applies any specified route prefix

8. Set Up Prisma Schema

The script:

1. Ensures the proper Prisma directory structure exists
2. Merges any Prisma schema files from the addon
3. Creates a migration for the merged schema

9. Generate Routes

Finally, the script runs the route generation process to update your application's routing.

Addon Source Options

Local Installation

When using the --source flag, you specify the exact directory containing the addon files. The script will:

1. Copy all files from the source directory to your project's addons directory
2. Process the addon.jsonc file to complete the installation

GitHub Installation

When using the --repo flag, you specify a GitHub repository URL. The script will:

1. Use degit to clone the repository into your project's addons directory
2. Process the addon.jsonc file to complete the installation

Troubleshooting

If you encounter issues during installation:

1. Missing addon.jsonc: Ensure the addon directory contains a valid addon.jsonc file
2. Failed package installation: Check that the required packages are available in npm
3. ShadCN component errors: Verify that the components listed in the addon.jsonc exist in the ShadCN UI library
4. Route conflicts: Check for route path conflicts with existing routes in your application

Advanced Usage

Custom Destination Directory

By default, addons are installed to src/app/addons, but you can specify a custom destination with the --dest flag:

node src/scripts/installAddon.mjs install suggest --source /path/to/suggest --dest /custom/path

Manual Configuration

After installation, you can manually edit the addon files in your project's addons directory to customize its behavior.

[peterp]

This is a thought I'm having out loud. We're going to put a lot of work into this format and to make sure that it does all the right things. However, I'm wondering whether we can just ignore this for now, focus on the documentation, and then ensure that some kind of AI agent does this? The reason why I bring this up is because I want to install Tailwind. We have really good documentation on that, and I pointed Gemini 2.5 at our documentation and said, "Figure out how to install Tailwind using this," and it did it perfectly. I'm not sure whether us being incredibly explicit about the process of installing these things and creating a new format is the way to go. I would suggest that we actually try and get away with just really good documentation.

Let's debate this because I know it's quite controversial. Where could it suck? And where could the approach, the file that we're suggesting suck?

[fecony]

This is cool, reminded me of Laravel package publishable assets, usually you just install package and it works, but you can also publish resources like routes, service provider, config and so on to adjust them when needed. new shadcn-like approach is nice addition to all of that

What I wonder, is how Shareware would prevent users from just installing and refunding code? likely not related to addons themselves, but something to think about I guess

I wonder also about what if users use drizzle, or other orm instead of the one that addon uses, or what if they dont use tailwind/shadcn and now have to handle this, then what if there is a bug in shadcn component, they have to wait for a fix, apply it? how changes are going to be applied? If developer adjusts the code that addon published, are they going to have to maintain it now and struggle if addon author reorders/renames files/folders?

I guess --source, --repo can be a single flag, basically repository is one of the sources itself, so there is no need for separate flag that does the same thing

addon json might have schema like shadcn registry has so that we know about properties there https://ui.shadcn.com/schema/registry-item.json

[peterp]

What I wonder, is how Shareware would prevent users from just installing and refunding code? likely not related to addons themselves, but something to think about I guess

This is really up to the author, and we will include a license that prevents usage if it hasn't been bought. I think you know if there is a user that is willing to take the code, install it in their own Cloud, and refund the money, they're probably just a bad actor, and there's nothing really that we can do to prevent that kind of piracy. They're not really the target market, so we have to accept some form of loss.

I wonder also about what if users use drizzle, or other orm instead of the one that addon uses

I have also thought really long and hard about what this looks like from an agnostic database perspective, and we're strongly considering whether to have a foundational layer that is neither Prisma nor Drizzle nor any ORM but just SQL. When you look at Cloudflare's durable objects, each durable object has its own database. A feature could also have its own database. I think specifically in the example that Amy shared, she's using a KV and not a database. But there's a lot of things that we're going to have to learn whilst building these.

what if they dont use tailwind/shadcn and now have to handle this

I don't know if we can be agnostic at the Tailwind/component level. But I'll think about how what that looks like, and if you have any ideas, I appreciate them.

[fecony]

And we're strongly considering whether to have a foundational layer that is neither Prisma nor Drizzle nor any ORM but just SQL.

Yes this is what I was thinking as well, in theory migrations are just SQL for both of them, but schema might differ, prisma use their dsl, drizzle uses their sqlite methods to define table, but migration code is just sql

Maybe the only approach there would be to assume that users agreeing to use addons have to follow some common practices, like Prisma, Tailwind, using Cloudflare features, so it's not a "blocker" for someone because they use tools in different way

But I'll think about how what that looks like, and if you have any ideas, I appreciate them.

I think Tailwind can be shipped both as just compiled styles that you import where needed, or like it is now, users compile it with their own styles, but there we would need to prevent them from custom styling breaking addon UI, or this is fine form of customization 😄

[Tobbe]

Another thing to consider is how to handle version requirements of RWSDK itself. Like if Add-On Foo depends on RWSDK v1.1.0, but the user only has v1.0.0. Or if the user wants to use Add-Ons Foo and Bar, but Foo needs RWSDK v1.1.0 and Bar needs RWSDK v2.0.0, how should that be handled?

I'd suggest all dependency requirements are left up to the Add-On author to handle. Just make sure they can actually get the info they need.

So the Add-On itself could check if the user's project is using Prisma, but the Add-On is built for Drizzle, then it'd be up to the Add-On to make that check and fail installation with an appropriate message.
Or the Add-On could go the extra mile and detect what ORM the user's app already has, and adapt to use that ORM internally as well.

Same for RWSDK versions. The Add-On could check to make sure the RWSDK version is compatible, and fail the installation with a helpful message if it isn't

[peterp]

how changes are going to be applied?

I just saw this on Hacker News, and it looks like this might be a format that would be very helpful. Something like this along with an agent AI agent could make this make a lot more sense:

[ahaywood]

@peterp I absolutely love AI, but I don't think it's the best or even easiest solution for everything. Here's a perfect example:

https://www.loom.com/share/fb57834b6a534d74a67861c66aef0d92

👆 Since you mentioned installing Tailwind. In the video, I have 3 IDE windows open.

1. Cursor - with a Tailwind script
2. Cursor - generic prompt to Gemini, telling it to install Tailwind.
3. Windsurf - running a custom workflow, where I've told everything it needs to do

Spoiler, results:

1. The script takes < ~5 seconds to run
2. Gemini eventually fails. I give Claude the same prompt, it was successful, but incorrect in it's implementation
3. Windsurf gets it faster than Cursor, but it takes ~3.5 minutes

I think AI will get there. But, in the meantime, I'd rather create a 🤯 mind blowing DX experience that "just works" every single time, with the same results.

With the script, I can install an add on in ~10 seconds max. That means, if I have a batch of tools (suggest, changelog, email config, blog, newsletter) I'm up in running in < 30 seconds. My Tailwind test was just Tailwind, it wasn't even a complex setup like what we're trying to do with Add Ons, it will easily take 5 minutes per add-on. With the 6 add-ons I mentioned, that means the setup will take ~30 minutes.

---

Update: I'm also wondering if there's some kind of hybrid approach here. Because I totally understand that a Cursor/Windsurf rule would be 1000x times easier to maintain and far more flexible than a script.

[ahaywood]

Other questions + answers:

think specifically in the example that Amy shared, she's using a KV and not a database. But there's a lot of things that we're going to have to learn whilst building these.

I'm not using KV for this. Everything is a node script.

what if they dont use tailwind/shadcn and now have to handle this

The script determines whether the user needs Tailwind and Shad or not. It doesn't install these every time. If the user has another package, it should be included in the package.json file and automatically installed.

Custom components would be included in the add-ons components directory and get included with the code.

version requirements of RWSDK itself

@Tobbe Great point! I can include a parameter within the addons.jsonc file.

I just saw this on Hacker News

@peterp Thanks for sharing! I'll take a look. I know at one point, shadcn/ui had a diff tool. I never used it, but I'll spike on it.

[arimendelow]

A lot of the conversation here is around dependencies, which makes sense as it's the most complex part of all this, so I want to add to the conversation the structure of the addons themselves — I see in the Loom that the suggest addon has a src directory in it. Is this intentional and required?

I also saw that it autoinstalled a Prisma schema merger tool — what's that about? Does it just ensure that the addon's prisma.schema is compatible with the root level prisma.schema, or does it actually merge it in? If the latter, why not just use multifile Prisma schemas? Is that even supported yet (I guess I should try it out 😆)? I love the idea of multifile schemas just from a colocation standpoint.

I ask these questions because while there are obvious boundaries that should be maintained for colocation purposes between a given addon and the rest of your app, I would still want every addon to be indistinguishable from the rest of my app.

And when we're talking about creating an agnostic database layer, I wonder if something similar can exist on the other end, in the UI layer. Probably not, as while SQL is SQL, != . Just a thought...

Also, just a tiny nit on this:

ShadCN components are detected by analyzing:

• Import statements with paths containing components/ui/
• Import statements with paths containing @/components/ui/ or @/app/components/ui/
• Relative imports with ./components/ui/ or ../components/ui/
• Direct JSX usage of component names

To be extra sure that shadcn/ui is being used, perhaps check for the components.json file?

[ahaywood]

I see in the Loom that the suggest addon has a src directory in it. Is this intentional and required?

This was accidental and has since been removed.

I also saw that it autoinstalled a Prisma schema merger tool

The Prisma merge tool will only be used if the user is using Prisma. -- We've had some additional conversations internally about what to do if the if use is using Drizzle, pure SQL, or something else. I have a few ideas.

I break down the merge tool in this Loom (11:13 mark): https://www.loom.com/share/d8562b61801d4a18ba4ef65967d8c10c?sid=15409498-fbf7-46d1-8114-23ab5bff3678 The clif notes:

• We can't leverage Prisma's multi-file solution because it wants everything to be within the prisma folder and the schema for the add-on is within the add-on folder.
• We can't simply move or copy the Prisma schema into the prisma folder because you can't have multiple models with the same name. For example, most of my add-ons require a User model. RedwoodSDK already ships with a User model. This can't be defined in multiple places. The two definitions need to be merged together.
• The merge tool takes the existing schema.prisma file and sticks it inside a schema folder and renames the file to schema.prisma.bak. Then, it merges together all the schema.prisma files (including schema.prisma.bak) into a single file.

To be extra sure that shadcn/ui is being used, perhaps check for the components.json file

Sure, I can add that check-in. I still need to look for import statements though. I can't just grab all the components within the ui folder because the user might be using shadcn/ui components in other places in the application that aren't necessary for the add-on.

---

More updates:

1. We're trying to determine the balance between leveraging AI and scripting. IMHO, I think there's going to be a balance between the two. Right now, scripting is faster, but there are so many edge cases it's hard to account for everything. Obviously, AI is much smarter and can figure a lot of those things out.

2. All add-on instructions will include manual instructions, as well. I'm just concerned by the number of steps:

   • Install Tailwind
   • Install shadcn/ui
   • Install these components
   • Import your CSS file
   • Merge your Prisma schema.
   • Create a new migration
   • Run your seed file
   • Set up these routes
   • Generate these routes in the shared/links folder.
   • Add these environmental variables

3. I'm also trying to think through the uninstall process. What happens when you install an add-on and then later decide you don't want it?

[arimendelow]

All makes sense, thank you Amy!!! On uninstall — I don't think you need to worry about that. That's the other side of taking ownership over a bit of code — users can use Git to confirm what changes are being made, but once something is installed, its theirs!

One thing, though, is future updates — what happens if I make changes to an addon I installed? I think for now it's enough to just have migration instructions.