Use as a Dependency

WARNING

This guide assumes that you know about secondary knowledge of JavaScript and Node.js. If you just started learning JavaScript development recently, or are not interested in coding, please Choose Other Installation Methods.

WARNING

It is strongly recommended to use template project for developing Koishi. If you are not sure what you are doing, it is recommended to read Template Project first.

While it is recommended to use the boilerplate project for most users, it would be more flexible when you directly embed Koishi as a dependency for your complicated application.

Initialize Your Project

TIP

Koishi is written with TypeScript, so TypeScript would be the first class programming language when you are developing Koishi. In the following section of documents, we will use TypeScript as example language. If you are writing vanilla JavaScript or other JavaScript dialects, you could modify your own code based on the example code.

Koishi requires Node.js (minimum v14, LTS is recommended) as the runtime environment. You should install it manually.Here we suppose you have it installed already.

Initialize a directly as your bot, install Koishi and common plugins, here we would install several official plugins as example: console, sandbox and echo.

npm

# Initialize project
npm init

# Install Koishi and plugins
npm i koishi @koishijs/plugin-console \
             @koishijs/plugin-sandbox \
             @koishijs/plugin-echo

# Install TypeScript and related packages (skip this if you don't use TypeScript)
npm i typescript @types/node esbuild esbuild-register -D

Create an entry file index.ts and write down the code below:

index.ts

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 new Koishi application
const ctx = new Context({
  port: 5140,
})

// Install plugins
ctx.plugin(console)     // Koishi Console
ctx.plugin(sandbox)     // Sandbox for debugging
ctx.plugin(echo)        // Echo command

// Launch the Koishi application
ctx.start()

Then launch this file:

node -r esbuild-register .

Finally, open your browser and enter http://localhost:5140, you will see the Console Web UI. Click the "Sandbox" icon on the left side, then click "Add User" button to create a simulated user. Now you can talk to the bot:

Alice

echo Bonjour

Koishi

Bonjour

Configure the Bot

If you want to connect the bot to a real chat platform, what you need to do is to install an adapter plugin:

npm

# Install the OneBot and Discord adapter as the example
npm i @koishijs/plugin-adapter-onebot @koishijs/plugin-adapter-discord

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

index.ts

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

// Apply the OneBot adapter to create a bot instance
ctx.plugin(onebot, {
  protocol: 'ws',
  selfId: '123456789',
  endpoint: 'ws://127.0.0.1:6700',
})

// Apply the OneBot adapter to create another bot instance
ctx.plugin(onebot, {
  protocol: 'http',
  selfId: '987654321',
  endpoint: 'http://127.0.0.1:5700',
})

// Apply the Discord adapter to create a bot instance
// You should install the corresponding plugins and complete the preparing process
ctx.plugin(discord, {
  token: 'QwErTyUiOpAsDfGhJkLzXcVbNm',
})

Add More Plugins

Koishi plugins could be installed from npm. Normally the name of Koishi plugins should follow the patterns described below:

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

As for community plugins, you could install and apply in a similar way:

npm

# As the example, install puppeteer and forward plugins
npm i koishi-plugin-puppeteer koishi-plugin-forward

index.ts

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

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

请注意到上面的两个插件的导入方式的微妙差异。puppeteer 插件使用了默认导出，而 forward 插件使用了导出的命名空间。这两种写法存在本质的区别，不能混用，因此你需要自行判断每个插件属于哪一种情况。虽然这可能产生一些困扰，但如果你是 TypeScript 用户，在类型提示的帮助下，判断一个插件属于哪一种情况是很轻松的。

同理，对于 commonjs 的使用者，如果要使用 require 来获取插件对象，也应注意到这种区别：

index.ts

// 这里的 .default 是不可省略的
ctx.plugin(require('koishi-plugin-puppeteer').default)

// 这里则不能写上 .default
ctx.plugin(require('koishi-plugin-forward'))

使用其他安装方式的用户不需要关心这些细节，因为模板项目已经帮你处理好了。

Apply Interaction

除了已经封装好的插件外，我们还可以添加自己的交互逻辑：

index.ts

// 如果收到“天王盖地虎”，就回应“宝塔镇河妖”
ctx.on('message', (session) => {
  if (session.content === '天王盖地虎') {
    session.send('宝塔镇河妖')
  }
})

然后重新运行你的项目：

Alice

天王盖地虎

Koishi

宝塔镇河妖

不过这样写可能并不好，因为一旦功能变多，你的 index.ts 就会变得臃肿。可以将上面的逻辑写在一个单独的文件 ping.ts 里，并将它作为一个插件来加载：

ping.ts

import { Context } from 'koishi'

export const name = 'ping'

export function apply(ctx: Context) {
  // 如果收到“天王盖地虎”，就回应“宝塔镇河妖”
  ctx.on('message', (session) => {
    if (session.content === '天王盖地虎') {
      session.send('宝塔镇河妖')
    }
  })
}

index.ts

// 这里的 ./ping 是相对于 index.ts 的路径
import * as ping from './ping'

ctx.plugin(ping)

What's next...

Congratulations that you have learnt the basic of Koishi! 接下来让我们前往开发指南，学习更多的 Koishi 知识。

Use as a Dependency ​

Initialize Your Project ​

Configure the Bot ​

Add More Plugins ​

Apply Interaction ​

What's next... ​

Use as a Dependency

Initialize Your Project

Configure the Bot

Add More Plugins

Apply Interaction

What's next...