Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Koishi
✓ import { Koishi } from 'koishi'
✗ const Koishi = require('koishi')
Koishi is designed for ES modules; CommonJS `require` might lead to issues in modern setups. Use named imports for core classes.
Context
✓ import { Context } from 'koishi'
The `Context` class is fundamental for creating plugins and managing application scope.
h
✓ import { h } from 'koishi'
The `h` function is used for creating message elements with a JSX-like syntax, enabling rich message formatting across platforms.
Schema
✓ import { Schema } from 'koishi'
Schema is used for defining plugin configurations and ensuring type safety and validation.
This quickstart demonstrates how to initialize a Koishi application, register a custom plugin, define a command, and set up a simple message listener. It highlights the use of `Context` for plugin development, `Schema` for configuration, and `h` for message formatting. A note on adapter configuration is included for a fully functional bot.
import { Context, Schema, h, Koishi } from 'koishi';
// In a real project, you would import and configure an adapter like:
// import '@koishijs/adapter-discord';
// Define a simple plugin
class MyHelloPlugin extends Context.Plugin {
static schema = Schema.object({
greeting: Schema.string().default('Hello').description('The greeting message.')
});
constructor(ctx: Context, config: { greeting: string }) {
super(ctx, config);
// Register a command
ctx.command('greet <target:string>', 'Greets someone')
.action(({ session }, target) => {
if (!target) return 'Please tell me who to greet!';
// Use h (Hyperscript) for rich message formatting, if supported by adapter
return h('message', [
h('text', `${config.greeting}, `),
h('at', { id: session?.userId || 'unknown' }), // Placeholder for @mention
h('text', ` ${target}! `)
]);
});
// Register a simple listener
ctx.on('message', (session) => {
if (session.content === 'ping') {
session.send('pong');
}
});
ctx.logger.info('MyHelloPlugin loaded!');
}
}
async function main() {
const app = new Koishi({
prefix: '.', // Command prefix
port: 8080, // WebUI port, if enabled
// The `plugins` object is where you configure adapters and other plugins.
// For this quickstart, we'll define a dummy adapter for demonstration.
// In a real app, you'd install and configure e.g., `@koishijs/adapter-discord`.
plugins: {
'my-hello-plugin': { // Directly add the plugin to the config
greeting: 'Hey there'
}
// Example of an actual adapter config (uncomment and replace with real token/platform):
// '@koishijs/adapter-discord': {
// token: process.env.DISCORD_TOKEN || 'YOUR_DISCORD_BOT_TOKEN',
// intents: 32767 // Or specific intents
// }
}
});
// Manually register the plugin class (usually done via `app.plugin()` or config)
app.plugin(MyHelloPlugin);
try {
await app.start();
console.log('Koishi application started. Listening for commands.');
console.log('Try to run a command like ".greet World" if an adapter is configured and connected.');
} catch (error) {
console.error('Failed to start Koishi:', error);
console.warn('Ensure you have installed and configured at least one adapter (e.g., @koishijs/adapter-discord) ' +
'and provided a valid token in the plugins config if you want to connect to a chat platform.');
}
}
main();
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in an ES module project (e.g., Node.js with `"type": "module"` or `.mjs` files). Koishi is primarily ESM-focused.
fixMigrate your project to use ES module `import`/`export` syntax. Ensure your `package.json` has `"type": "module"`.
TypeError: Cannot read properties of undefined (reading 'send')
Attempting to send a message from a `session` object where `session.send` is undefined, often because the session is not associated with a valid adapter or the event context does not support sending messages.
fixEnsure the command or listener is invoked in a context where a valid `session` object with a connected adapter is available. Check that your Koishi instance has at least one adapter configured and successfully connected to a platform.
Audit
Dependencies
No dependency data recorded yet.