Install as a dependency

WARNING

This guide assumes that you already have intermediate knowledge of JavaScript and Node.js. If you are just starting to learn JavaScript or not interested in writing business code, please Choose Other Installation Methods.

WARNING

We strongly recommend using a template project for Koishi development. If you are unsure about what you are doing, it is advisable to read the Template Project section thoroughly.

While we recommend the use of the boilerplate for most users, it would be a more flexible choice if you directly embed Koishi as the dependency for your complex application.

Initializing Your Project

TIP

The Koishi itself is written in TypeScript, so we recommend using TypeScript for Koishi development. In the following documentation, we will consistently use TypeScript as an example. If you are writing vanilla JavaScript or other JavaScript dialects, you could make modifications for your own code based on the example one.

Koishi requires a Node.js runtime environment (at least v18, suggested to use LTS versions), you need to install it yourself.We assume that you have already installed it.

Firstly initialize your bot directory, then install Koishi and the necessary plugins (in this example, we use the official plugins such as console, sandbox, and echo):

npmyarn

# 初始化项目
npm init

# 安装 Koishi 和相关插件
npm i koishi \
      @koishijs/plugin-console \
      @koishijs/plugin-sandbox \
      @koishijs/plugin-echo

# 安装 TypeScript 相关依赖 (如不使用可忽略此步骤)
npm i typescript @types/node esbuild esbuild-register -D

Create a new entry file index.ts and write the following code:

import { Context } from 'koishi'
import console from '@koishijs/plugin-console'
import * as sandbox from '@koishijs/plugin-sandbox'
import * as echo from '@koishijs/plugin-echo'

// Create a Koishi instance
const ctx = new Context({
  port: 5140,
})

// Enable the above plugins
ctx.plugin(console)     // Provides a console
ctx.plugin(sandbox)     // Provides a debugging sandbox
ctx.plugin(echo)        // Provides an echo command

// Start the application
ctx.start()

Then run this file:

node -r esbuild-register .

Finally, open your browser and go to http://localhost:5140. You will see the Koishi Console WebUI. Click on the "Sandbox" icon on the left and click "Add User" at the top of the screen to create a virtual user. Now you can interact with the bot:

A

Alice

echo Bonjour

Koishi

Bonjour

Configuring Your Bot

If you want to integrate your bot with an actual chat platform, you just need to install the appropriate adapter plugins:

npmyarn

# 以 Satori 和 Discord 适配器为例
npm i @koishijs/plugin-adapter-satori \
      @koishijs/plugin-adapter-discord

Then modify the index.ts file you created earlier. Every time you activated an adapter plugin instance, a new bot instance would be created:

import satori from '@koishijs/plugin-adapter-satori'
import discord from '@koishijs/plugin-adapter-discord'

// Using the Satori adapter for one bot
ctx.plugin(satori, {
  endpoint: 'http://127.0.0.1:5500',
})

// Using the Satori adapter for another bot with different communication methods
ctx.plugin(satori, {
  endpoint: 'http://127.0.0.1:5501',
})

// Using the Discord adapter for a bot
// Don't forget to install the appropriate plugins and complete the setup before using it
ctx.plugin(discord, {
  token: 'QwErTyUiOpAsDfGhJkLzXcVbNm',
})

Adding More Plugins

Koishi plugins could be obtained from npm. Typically, plugins follow one of these naming conventions:

• koishi-plugin-foo
• @koishijs/plugin-foo
• @bar/koishi-plugin-foo

For community plugins, you can install and load them similarly:

npmyarn

# Using puppeteer and forward plugins as examples
npm i koishi-plugin-puppeteer koishi-plugin-forward

import puppeteer from 'koishi-plugin-puppeteer'
import * as forward from 'koishi-plugin-forward'

ctx.plugin(puppeteer)   // Provides browser service
ctx.plugin(forward)     // Provides message forwarding

Please note the subtle difference in importing the two plugins above. The puppeteer plugin uses default export, while the forward plugin uses a named export namespace. These two approaches are fundamentally different and cannot be mixed, so you need to determine which category each plugin falls into. Although this may cause some confusion, if you are a TypeScript user, determining which category a plugin belongs to is easy with the help of type hints.

Likewise, for CommonJS users who want to use require to get the plugin object, you should also pay attention to this distinction:

// .default is required here
ctx.plugin(require('koishi-plugin-puppeteer').default)

// .default should not be added here
ctx.plugin(require('koishi-plugin-forward'))

Users of other installation methods do not need to worry about this distinction, because the boilerplate handles them for you.

Adding Interaction Logic

除了使用发布在 npm 上的插件，我们还可以添加自己的交互逻辑：

// Reply with "world", after receiving "Hello"
  ctx.on('message', (session) => {
    if (session.content === 'Hello') {
      session.send('world')
    }
  })

Then run your project again:

A

Alice

Hello

Koishi

world

However, this may be worse because as your features grow, your index.ts file will become cumbersome. You can write the above logic in a separate file such as ping.ts, and then load it as a plugin:

import { Context } from 'koishi'

export const name = 'ping'

export function apply(ctx: Context) {
  // Reply with "world", after receiving "Hello"
  ctx.on('message', (session) => {
    if (session.content === 'Hello') {
      session.send('world')
    }
  })
}

// Here the ./ping is the path to index.ts
import * as ping from './ping'

ctx.plugin(ping)

What's Next...

Congratulations on mastering the basic of Koishi! Next, let's go to developing guide to learn more about Koishi.