feat: Add type doc to build doc for project. (#282)

README.md

@@ -31,3 +31,66 @@ Outputs will be built in the `lib` directory in their own workspaces
 ## Demos
 
 [MVP DApp](./packages/samples/mvp-dapp)
+
+## Quick start
+
+#### Environment
+
+    node >= 18
+
+#### Kuai Installation
+
+First, install `kuai` globally by `npm link`:
+
+```bash
+$ git clone git@github.com:ckb-js/kuai.git
+
+$ cd kuai
+
+$ yarn bootstrap
+
+$ yarn build
+
+$ cd packages/cli
+
+$ npm link
+```
+
+#### Create a template project using the command.
+
+```bash
+kuai init
+```
+
+#### Running
+
+`kuai` has `dev` and `prod` modes
+
+dev
+
+```bash
+npm run dev
+```
+
+prod
+
+```bash
+npm run build
+npm run start:prod
+```
+
+#### Others commands
+
+run test
+
+```bash
+npm run test
+```
+
+build docs
+
+The docs is build by [typedoc](https://typedoc.org/), `typedoc.json` is the build configuration.
+
+```bash
+npm run doc
+```

packages/core/recommended-package.json

@@ -5,6 +5,7 @@
     "build": "tsc",
     "build:watch": "tsc -w",
     "start:prod": "node ./dist/main.js",
-    "test": "jest"
+    "test": "jest",
+    "doc": "typedoc"
   }
 }

packages/core/sample-projects/Development.md

@@ -0,0 +1,26 @@
+# Development
+
+## Environment
+
+You should start a redis service. And the redis's default port is 6379. You can edit it at `kuai.config.ts`
+
+```typescript
+import { KuaiConfig } from '@ckb-js/kuai-core';
+
+const config: KuaiConfig = {
+  REDIS_PORT: 6379,
+};
+
+export default config;
+```
+
+## Quick Start
+
+```sh
+git clone <remote_repository_location>
+cd <project name>
+npm install
+npm run dev
+```
+
+It will start a service at `http://127.0.0.1:3000`, try to open [hello](http://127.0.0.1:3000)

packages/core/sample-projects/kuai.config.ts

@@ -2,6 +2,10 @@ import { KuaiConfig } from '@ckb-js/kuai-core';
 
 const config: KuaiConfig = {
   port: 3000,
+  ckbChain: {
+    rpcUrl: 'http://127.0.0.1:8114',
+    prefix: 'ckt',
+  },
 };
 
 export default config;

packages/core/sample-projects/src/actors/app.ts

@@ -9,7 +9,7 @@ interface HelloMessage {
 
 export type AppMessage = HelloMessage;
 
-@ActorProvider({ name: 'app' }, true)
+@ActorProvider({ ref: { name: 'app' }, autoBind: true })
 export class CustomActor extends Actor<object, MessagePayload<AppMessage>> {
   handleCall = (_msg: ActorMessage<MessagePayload<AppMessage>>): void => {
     switch (_msg.payload?.value?.type) {

packages/core/sample-projects/src/app.controller.ts

@@ -1,27 +1,27 @@
-import { KuaiRouter } from '@ckb-js/kuai-io';
+import { BaseController, Controller, Get, Query } from '@ckb-js/kuai-io';
 import { appRegistry } from './actors';
-import { Actor } from '@ckb-js/kuai-models';
+import { Actor, ActorNotFoundException } from '@ckb-js/kuai-models';
 
-const router = new KuaiRouter();
+@Controller('/')
+export default class AppController extends BaseController {
+  @Get('/')
+  async hello(@Query('name') name: string) {
+    const appActor = appRegistry.find('local://app');
 
-router.get('/', async (ctx) => {
-  const appActor = appRegistry.find('local://app');
+    if (!appActor) {
+      throw new ActorNotFoundException('local://app');
+    }
 
-  if (!appActor) {
-    return ctx.err('not found app actor');
-  }
-
-  await Actor.call(appActor.ref.uri, appActor.ref, {
-    pattern: 'normal',
-    value: {
-      type: 'hello',
-      hello: {
-        name: ctx?.payload?.query?.name,
+    await Actor.call(appActor.ref.uri, appActor.ref, {
+      pattern: 'normal',
+      value: {
+        type: 'hello',
+        hello: {
+          name,
+        },
       },
-    },
-  });
+    });
 
-  ctx.ok(`hello ${ctx?.payload?.query?.name || 'world'}`);
-});
-
-export { router };
+    return `hello ${name || 'world'}`;
+  }
+}

packages/core/sample-projects/src/main.ts

@@ -2,7 +2,7 @@ import Koa from 'koa';
 import { koaBody } from 'koa-body';
 import { initialKuai } from '@ckb-js/kuai-core';
 import { KoaRouterAdapter, CoR } from '@ckb-js/kuai-io';
-import { router } from './app.controller';
+import AppController from './app.controller';
 import './type-extends';
 
 async function bootstrap() {
@@ -15,7 +15,8 @@ async function bootstrap() {
 
   // init kuai io
   const cor = new CoR();
-  cor.use(router.middleware());
+  const appController = new AppController();
+  cor.use(appController.middleware());
 
   const koaRouterAdapter = new KoaRouterAdapter(cor);
 

packages/core/sample-projects/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/main.ts", "./**/*.controller.ts"],
+  "out": "docs"
+}

packages/core/src/project-creation.ts

@@ -26,6 +26,7 @@ const DEPENDENCIES: Dependencies = {
 const DEV_DEPENDENCIES: Dependencies = {
   'ts-node': '10.9.1',
   typescript: '4.9.4',
+  typedoc: '0.24.7',
 }
 
 const KUAI_DEPENDENCIES: Dependencies = {
@@ -55,8 +56,6 @@ async function printWelcomeMessage() {
 async function copySampleProject(projectRoot: string) {
   const packageRoot = getPackageRoot()
 
-  fs.existsSync(projectRoot)
-
   const sampleProjectPath = path.join(packageRoot, 'sample-projects')
 
   const sampleProjectRootFiles = fs.readdirSync(sampleProjectPath)
@@ -90,24 +89,24 @@ async function addGitIgnore(projectRoot: string) {
   fs.writeFileSync(gitIgnorePath, content)
 }
 
-async function canInstallRecommendedDeps() {
+async function canInstallRecommendedDeps(packageJsonPath: string) {
   return (
-    fs.existsSync('package.json') &&
+    fs.existsSync(packageJsonPath) &&
     // TODO: Figure out why this doesn't work on Win
     // cf. https://github.com/nomiclabs/hardhat/issues/1698
     os.type() !== 'Windows_NT'
   )
 }
 
-async function installRecommendedDependencies(dependencies: Dependencies, dev = false) {
+async function installRecommendedDependencies(projectRoot: string, dependencies: Dependencies, dev = false) {
   console.log('')
 
   const deps = Object.entries(dependencies).map(([name, version]) => `${name}@${version}`)
 
   // The reason we don't quote the dependencies here is because they are going
   // to be used in child_process.sapwn, which doesn't require escaping string,
   // and can actually fail if you do.
-  return installDependencies('npm', ['install', dev ? '--save-dev' : '--save', ...deps])
+  return runCommand('npm', ['install', dev ? '--save-dev' : '--save', '-E', ...deps], projectRoot)
 }
 
 async function getNpmLinksText(): Promise<string> {
@@ -163,10 +162,10 @@ async function getNpmLinks(): Promise<Array<NpmLink>> {
 async function checkLocalKuaiLink() {
   const links = await getNpmLinks()
 
-  return !Object.keys(KUAI_DEPENDENCIES).some((kuaiDep) => links.findIndex((link) => link.name === kuaiDep) === -1)
+  return Object.keys(KUAI_DEPENDENCIES).every((kuaiDep) => links.findIndex((link) => link.name === kuaiDep) !== -1)
 }
 
-async function installKuaiDependencies() {
+async function installKuaiDependencies(projectRoot: string) {
   if (await checkLocalKuaiLink()) {
     const { shouldUseLocalKuaiPackages } = await prompt<{ shouldUseLocalKuaiPackages: boolean }>({
       name: 'shouldUseLocalKuaiPackages',
@@ -176,18 +175,19 @@ async function installKuaiDependencies() {
     })
 
     if (shouldUseLocalKuaiPackages) {
-      return installDependencies('npm', ['link', ...Object.keys(KUAI_DEPENDENCIES)]).then(() => {
-        console.info(`✨ Link local kuai package successed ✨\n`)
-      })
+      await runCommand('npm', ['link', ...Object.keys(KUAI_DEPENDENCIES)], projectRoot)
+      console.info(`✨ Link local kuai package successed ✨\n`)
     }
   }
 
-  return installRecommendedDependencies(KUAI_DEPENDENCIES, false)
+  console.info('add kuai depende into package')
+  return installRecommendedDependencies(projectRoot, KUAI_DEPENDENCIES, false)
 }
 
-async function installDependencies(command: string, args: string[]): Promise<boolean> {
+async function runCommand(command: string, args: string[], projectRoot?: string): Promise<boolean> {
   const childProcess = spawn(command, args, {
     stdio: 'inherit',
+    cwd: projectRoot,
   })
 
   return new Promise((resolve, reject) => {
@@ -209,11 +209,11 @@ async function installDependencies(command: string, args: string[]): Promise<boo
   })
 }
 
-async function createPackageJson(mergedPackageJson?: unknown) {
+async function createPackageJson(packageJsonPath: string, mergedPackageJson?: unknown) {
   const recommendProjectJson = await getRecommendedPackageJson()
   const mergedPackage = merge(recommendProjectJson, mergedPackageJson)
 
-  fs.writeFileSync('package.json', JSON.stringify(mergedPackage, null, 2) + os.EOL)
+  fs.writeFileSync(packageJsonPath, JSON.stringify(mergedPackage, null, 2) + os.EOL)
 }
 
 export async function createProject(): Promise<void> {
@@ -235,8 +235,21 @@ export async function createProject(): Promise<void> {
     message: 'Do you want to add a .gitignore?',
   })
 
+  const { shouldBuildDoc } = await prompt<{ shouldBuildDoc: boolean }>({
+    name: 'shouldBuildDoc',
+    type: 'confirm',
+    initial: true,
+    message: 'Do you want to build doc after create project?',
+  })
+
+  if (!fs.existsSync(projectRoot)) {
+    fs.mkdirSync(projectRoot, { recursive: true })
+  }
+
+  const packageJsonPath = path.join(projectRoot, 'package.json')
+
   const existedPackageJson = await (async () => {
-    if (!fs.existsSync('package.json')) {
+    if (!fs.existsSync(packageJsonPath)) {
       return
     }
 
@@ -250,26 +263,31 @@ export async function createProject(): Promise<void> {
 
     if (shouldMergePackageJson) {
       try {
-        return JSON.parse(fs.readFileSync('package.json', 'utf-8'))
+        return JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
       } catch (e) {
         console.error(`We couldn't initialize the sample project because package.json is not a valid JSON file.`)
         throw e
       }
     }
   })()
 
-  await createPackageJson(existedPackageJson)
+  await createPackageJson(packageJsonPath, existedPackageJson)
 
   if (shouldAddGitIgnore) {
     await addGitIgnore(projectRoot)
   }
 
   await copySampleProject(projectRoot)
 
-  if (await canInstallRecommendedDeps()) {
-    await installRecommendedDependencies(DEPENDENCIES, false)
-    await installRecommendedDependencies(DEV_DEPENDENCIES, true)
-    await installKuaiDependencies()
+  if (await canInstallRecommendedDeps(packageJsonPath)) {
+    await installKuaiDependencies(projectRoot)
+    await installRecommendedDependencies(projectRoot, DEPENDENCIES, false)
+    await installRecommendedDependencies(projectRoot, DEV_DEPENDENCIES, true)
+  }
+
+  if (shouldBuildDoc) {
+    await runCommand('npm', ['run', 'doc'], projectRoot)
+    console.info(`✨ doc build success, you can see it at ./docs ✨\n`)
   }
 
   console.info(`✨ Project created ✨\n`)