🌱 Seeding

Sometimes plugins recommend or require certain files to be present in your project. Seeding is a way to automate this process.

Seed on Install

When you install a plugin with the Robo CLI, you may be asked if you want files included and a description of them.

Terminal

npx robo add @robojs/server

For example, the @robojs/server plugin may seed optional files in /src/api that shows how to use it. They are optional and can be deleted if you don't want them.

You can also deny seeding by using the --no-seed flag or by entering n when prompted.

📦 Installing plugin
   ✔ @robojs/server

🌱 Seed files detected
   - @robojs/server: Example API route and index page

   Would you like to include these files? [Y/n]: n

✨ Plugin successfully installed and ready to use.

If you opted out of seeding, you can always add them later by running robo add again.

🔌 Robo Plugins

Add features to your Robo seamlessly.

TypeScript

Seeds are smart enough to detect if you're using TypeScript and seed .ts files instead of .js.

However, this is only true if the plugin developer provided TypeScript files in the seed. If they didn't, you'll get JavaScript files instead even if you're using TypeScript.

If you're a plugin developer, we highly recommend providing .ts files in the seed, even if your plugin wasn't written in TypeScript. This way, users can benefit from type safety right away. The Robo Compiler will automatically compile them to JavaScript for those who don't use TypeScript.

You can also provide both .ts and .js files if you want finer control over the output instead of relying on the compiler.

📘 TypeScript

Write better code with type safety.

Use Cases

Seeding is useful for all kind of things, such as examples, databases, configurations, and more. Here's a list:

• Example files to get you started
• Configuration files
• Database files
• Complex setups
• Boilerplates

Plugins can seed anything they want, and it's up to you to decide if you want them or not.

Plugin Developers

If you're developing a plugin and want users to have certain files in their project, you can seed them by creating a /seed folder in your plugin's root directory.

Anything you put in /seed gets copied to the user's /src directory. If you want to copy files into the root directory, you can use the /seed/_root folder.

/seed
├── /_root
│   └── index.html
└── /api
    └── hello.ts

When the user installs your plugin, these files are copied to their project if they approve.

While optional, a description of the files is recommended to help users understand what they are getting. You can provide a description in your plugin's Robo Config file:

robo.mjs

export default {
	// ... rest of config
	seed: {
		description: 'Example API route and index page'
	}
}

Now when users install your plugin with robo add, they will see a description of the files being seeded before they decide to include them. This helps them make an informed decision.

🔌 Creating Plugins

Make your own plugins for Robo.js.

Environment Variable Seeding

In addition to copying files, plugins can seed environment variables. Robo surfaces the additions before asking for confirmation so users understand exactly what will be written.

🔑 Environment additions detected
   - @robojs/auth: Adds secure defaults for authentication flows.
        AUTH_SECRET – Secret used to sign and verify authentication payloads.
    Target files: .env

    Add these variables to .env? [Y/n]: Y

🔑 Environment variables applied
   ✔ @robojs/auth added AUTH_SECRET

Declaring Static Keys

Add static values under seed.env.variables. Robo merges these into any detected .env* files without overwriting existing keys unless you explicitly opt in.

robo.config.ts

import type { Config } from 'robo.js'

const config: Config = {
	seed: {
		description: 'Adds environment defaults for Auth.',
		env: {
			description: 'Secures authentication payloads.',
			variables: {
				AUTH_SECRET: {
					description: 'Secret used to sign and verify authentication payloads.',
					overwrite: false,
					value: 'replace-me'
				}
			}
		}
	}
}

export default config

Generating Values with Hooks

Use seed.hook when you need to compute values on the fly or tweak the seeding experience. The hook runs before Robo shows the prompt, and anything you return is merged into the seed config—perfect for populating environment variables without shipping a separate file.

robo.config.ts

import type { Config } from 'robo.js'

export default <Config>{
	seed: {
		description: 'Initializes Auth secrets.',
		hook: async ({ generators }) => {
			const secret = generators.randomHex(32)

			return {
				env: {
					description: 'Generates a unique AUTH_SECRET.',
					variables: {
						AUTH_SECRET: {
							description: 'Secret used to sign and verify authentication payloads.',
							overwrite: false,
							value: secret
						}
					}
				}
			}
		}
	}
}

Hooks run before Robo asks the user to confirm the changes. The inline function return value mirrors the seed config, so you can mix static variables with computed ones or leave the hook to handle everything dynamically.

Helpful Utilities

Within hooks, the helpers.generators bundle exposes:

• randomHex(bytes?: number) – cryptographically strong hex strings.
• randomBase64(bytes?: number) – base64 strings without padding.
• randomUUID() – UUID v4 values.

The helpers.log method prints to the installer's console with the plugin prefix, useful when debugging seeding logic.

Hooks are inline only—there's no need to manage separate files. Robo compiles the function into the manifest automatically.

Limitations

Seeds cannot be used to modify existing files in the project for security reasons. They can only add new files.

Similarly, seeds can only affect the Robo project they are installed in. They cannot modify other projects or files outside of the project's directory.