Configuration

Makoo is configured through the makoo() Vite plugin. This file describes project-level behavior: how Makoo scans modules, which runtime defaults it should use, and how the final userscript is passed to vite-plugin-monkey.

import { defineConfig } from 'vite';
import { makoo } from '@makoojs/cli';

export default defineConfig({
	plugins: [
		makoo({
			app: {
				name: 'my-script',
				version: '0.0.1',
				description: 'Enhance example.com with injected UI'
			},
			source: {
				include: ['*'],
				exclude: []
			},
			injector: {
				alive: false,
				scope: 'local',
				timeout: 5000
			},
			runtime: {
				setup: ['./injections/setup.ts']
			},
			monkey: {
				userscript: {
					match: ['https://example.com/*']
				}
			}
		})
	]
});

Use vite.config.ts for settings that affect the whole project. Use injections/manifest.ts for module-level behavior such as injectAt, component, match, alive, and hooks for a specific injection.

Option Groups

Group	Purpose
app	Makoo app metadata and default userscript name/version
source	Which module folders are scanned under injections/
injector	Runtime defaults inherited by modules
runtime	Side-effect setup files imported before injector setup
monkey	vite-plugin-monkey userscript, server, and build options

app

app is required.

makoo({
	app: {
		name: 'my-script',
		version: '0.0.1',
		description: 'Optional script description'
	}
});

Field	Description
name	Required app name. Also becomes the default userscript name
version	Required version. Also becomes the default userscript version
description	Optional description. Also becomes the default userscript description

Values in monkey.userscript can still override the generated userscript metadata when you need more control.

source

source controls module scanning.

makoo({
	source: {
		include: ['*'],
		exclude: ['draft-*']
	}
});

Makoo currently scans the fixed injections/ directory. The top-level manifest file is also fixed to manifest, so Makoo will look for files such as injections/manifest.ts and module-level files such as injections/panel/manifest.ts.

Field	Default	Description
include	['*']	Folder-name patterns to include under injections/
exclude	[]	Folder-name patterns to exclude under injections/

These patterns filter module folders, not page URLs. For page URL matching, use monkey.userscript.match for the whole userscript or module-level match in the manifest.

injector

injector defines runtime defaults for modules.

makoo({
	injector: {
		alive: false,
		scope: 'local',
		timeout: 5000,
		hooks: {
			'run:start': (payload) => {
				console.log('[makoo] run started', payload);
			}
		}
	}
});

Field	Default	Description
alive	false	Whether modules should reinject when their mount disappears
scope	'local'	Reinjection observation scope, either 'local' or 'global'
timeout	5000	Time in milliseconds to wait for each target selector
hooks	{}	Global lifecycle hooks

Modules inherit these defaults unless they set their own alive, scope, timeout, or hooks in the manifest. A top-level manifest can also provide globalInjector, which is resolved as the runtime injector config for the scanned injection set.

runtime

runtime.setup imports side-effect files before Makoo creates and runs the injector.

makoo({
	runtime: {
		setup: ['./injections/setup.ts', './injections/polyfills.ts']
	}
});

Use setup files for project-wide runtime preparation, such as installing globals, initializing shared services, or importing side-effect styles. Makoo tracks setup files and their local dependencies during development, so changing them triggers a structural update.

monkey

Most monkey options are passed to vite-plugin-monkey.

makoo({
	monkey: {
		userscript: {
			namespace: 'npm/makoo',
			match: ['https://example.com/*'],
			grant: ['GM_getValue', 'GM_setValue']
		},
		server: {
			open: true,
			prefix: 'server:'
		},
		build: {
			fileName: 'my-script.user.js',
			metaFileName: true,
			autoGrant: true
		}
	}
});

Makoo manages a few vite-plugin-monkey details internally:

Option	Makoo behavior
entry	Generated by Makoo
clientAlias	Fixed internally
server.mountGmApi	Fixed internally

Do not set monkey.clientAlias or monkey.server.mountGmApi; Makoo validates and rejects those options because they would conflict with its runtime integration.

Defaults

The main defaults are:

Option	Default
source.include	['*']
source.exclude	[]
injector.alive	false
injector.scope	'local'
injector.timeout	5000
runtime.setup	[]
monkey.align	2
monkey.styleImport	true
monkey.server.prefix	'server:'
monkey.build.fileName	${app.name}.user.js
monkey.build.metaFileName	false
monkey.build.autoGrant	true

Configuration Boundary

Keep this split in mind:

File	Owns
vite.config.ts	Project metadata, scanning, global runtime defaults, userscript build/dev options
injections/manifest.ts	Injection modules, target selectors, component paths, module URL rules
injections/<module>/	Component code, module styles, module helpers, optional module manifest

This boundary keeps Makoo projects understandable as they grow.