Merge pull request #389 from 0808zhongshang/dubbo3
docs
diff --git a/.husky/commit-msg b/.husky/commit-msg
new file mode 100644
index 0000000..314e821
--- /dev/null
+++ b/.husky/commit-msg
@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no-install commitlint --edit $1
\ No newline at end of file
diff --git a/commitlint.config.js b/commitlint.config.js
new file mode 100644
index 0000000..04c7b8d
--- /dev/null
+++ b/commitlint.config.js
@@ -0,0 +1,32 @@
+module.exports = {
+ extends: ['@commitlint/config-conventional'],
+ rules: {
+ 'body-leading-blank': [2, 'always'],
+ 'footer-leading-blank': [1, 'always'],
+ 'header-max-length': [2, 'always', 108],
+ 'subject-empty': [2, 'never'],
+ 'type-empty': [2, 'never'],
+ 'subject-case': [0],
+ 'type-enum': [
+ 2,
+ 'always',
+ [
+ 'feat',
+ 'fix',
+ 'perf',
+ 'style',
+ 'docs',
+ 'test',
+ 'refactor',
+ 'build',
+ 'ci',
+ 'chore',
+ 'revert',
+ 'wip',
+ 'workflow',
+ 'types',
+ 'release',
+ ],
+ ],
+ },
+}
diff --git a/docs/guide/dubboForWEB/CommonErrors.md b/docs/guide/dubboForWEB/CommonErrors.md
index 7293ed7..afac889 100644
--- a/docs/guide/dubboForWEB/CommonErrors.md
+++ b/docs/guide/dubboForWEB/CommonErrors.md
@@ -1 +1,45 @@
-# CommonErrors
+# Common errors
+
+This section introduces common errors encountered when using Dubbo-js in browser and their corresponding solutions.
+
+## CORS issues arise in browser requests
+
+Cross-origin issues stem from the Content Security Policy (CSP) of the browser, which prevents a page from properly handling responses when the browser sends a request whose URL differs in **scheme, domain, or port** from the target server's URL. For more detailed information, please refer to [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+
+To tackle this issue, our recommended approach is to configure CORS on the target server.
+
+1. For a native Node.js server:
+```typescript
+import { createServer } from "http";
+import { dubboNodeAdapter } from "@apachedubbo/dubbo-node";
+import dubboRoutes from "./router";
+
+const server = createServer((req, res) => {
+ res.setHeader("Access-Control-Allow-Origin", "*");
+ res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+ res.setHeader("Access-Control-Allow-Headers", "*");
+ // replace "dubbo" with your actual service group
+ res.setHeader("Tri-Service-Group", "dubbo");
+ // replace "1.0.0" with your actual service version
+ res.setHeader("Tri-Service-Version", "1.0.0");
+
+ // Handling the preflight request (OPTIONS)
+ if (req.method === "OPTIONS") {
+ res.end();
+ return;
+ }
+
+ const handler = dubboNodeAdapter({
+ routes: dubboRoutes
+ });
+ handler(req, res);
+});
+
+server.listen(8000, () => {
+ console.log("\ndubbo-js server is running on http://localhost:8000...\n");
+});
+```
+2. For servers employing Node.js frameworks, we have devised some more convenient solutions to certain frameworks:
+- [express](/todo)
+- [fastify](/todo)
+- [next](/todo)
diff --git a/docs/guide/dubboForWEB/GettingStarted.md b/docs/guide/dubboForWEB/GettingStarted.md
index bad5562..ed7ec24 100644
--- a/docs/guide/dubboForWEB/GettingStarted.md
+++ b/docs/guide/dubboForWEB/GettingStarted.md
@@ -1 +1,172 @@
-# Getting Started
+# Getting started
+
+## What is Dubbo-js
+Dubbo-js is the TypeScript implementation of [Dubbo triple protocol (a fully gRPC compatible and http friendly protocol)](https://dubbo.apach.org/zh-cn/overview/reference/protocols/triple-spec/), which can be used for Node.js and web application development. With dubbo-js, you can easily build applications working on browser and frontend that can communicate with backend services through http-based protocol.
+
+
+
+## Prerequisites
+
+- Have the latest version of Node.js installed.
+- Operate a server that employs the Dubbo ecosystem and provides interfaces.
+- Install the necessary dependencies:
+
+```shell
+ npm install @apachedubbo/dubbo @apachedubbo/dubbo-web
+```
+
+## Usage
+
+There are two modes for using Dubbo-js in the frontend, primarily differing based on whether or not an IDL has been generated.
+
+### Without an existing IDL
+
+In scenarios where no IDL is available, the first step involves defining a service using Proto:
+
+```Shell
+mkdir -p src/util/proto && touch src/util/proto/example.proto
+```
+
+Subsequently, populate it with content:
+
+```Protobuf
+syntax = "proto3";
+
+package apache.dubbo.demo.example.v1;
+
+message SayRequest {
+ string sentence = 1;
+}
+
+message SayResponse {
+ string sentence = 1;
+}
+
+service ExampleService {
+ rpc Say(SayRequest) returns (SayResponse) {}
+}
+```
+
+This file declares a service named `ExampleService` and defines its `Say` method along with its request parameter `SayRequest` and response parameter `SayResponse`.
+
+Before generating code, ensure that you have **globally** installed the required dependencie
+
+```shell
+npm install -g @bufbuild/protoc-gen-es @apachedubbo/protoc-gen-apache-dubbo-es
+```
+
+After installing these dependencies, execute the following commands to generate the code：
+> Note: Replace the relative paths in the command according to your actual setup.
+
+```Shell
+ protoc -I src/util/proto \
+ --es_out src/util/gen \
+ --es_opt target=ts \
+ --apache-dubbo-es_out src/util/gen \
+ --apache-dubbo-es_opt target=ts \
+ example.proto
+```
+
+Upon completion, you should find the `example_dubbo.ts` and `example_pb.ts` files in the specified output location.
+
+The final step is incorporating them into your frontend project. Below is an example using a React app：
+
+```typescript
+import { useState } from "react";
+import "./App.css";
+
+import { createPromiseClient } from "@apachedubbo/dubbo";
+import { createDubboTransport } from "@apachedubbo/dubbo-web";
+
+// Import service definition that you want to connect to.
+import { ExampleService } from "./util/gen/example_dubbo";
+
+// The transport defines what type of endpoint we're hitting.
+// In our example we'll be communicating with a Dubbo endpoint.
+const transport = createDubboTransport({
+ baseUrl: "http://localhost:8080",
+});
+
+// Here we make the client itself, combining the service
+// definition with the transport.
+const client = createPromiseClient(ExampleService, transport, { serviceGroup: 'dubbo', serviceVersion: '1.0.0' });
+
+function App() {
+ const [inputValue, setInputValue] = useState("");
+ const [messages, setMessages] = useState<
+ {
+ fromMe: boolean;
+ message: string;
+ }[]
+ >([]);
+ return (
+ <>
+ <ol>
+ {messages.map((msg, index) => (
+ <li key={index}>{`${msg.fromMe ? "ME:" : "Dubbo Server:"} ${msg.message}`}</li>
+ ))}
+ </ol>
+ <form
+ onSubmit={async (e) => {
+ e.preventDefault();
+ // Clear inputValue since the user has submitted.
+ setInputValue("");
+ // Store the inputValue in the chain of messages and
+ // mark this message as coming from "me"
+ setMessages((prev) => [
+ ...prev,
+ {
+ fromMe: true,
+ message: inputValue,
+ },
+ ]);
+ const response = await client.say({
+ sentence: inputValue,
+ });
+ setMessages((prev) => [
+ ...prev,
+ {
+ fromMe: false,
+ message: response.sentence,
+ },
+ ]);
+ }}
+ >
+ <input value={inputValue} onChange={(e) => setInputValue(e.target.value)} />
+ <button type="submit">Send</button>
+ </form>
+ </>
+ );
+}
+
+export default App;
+```
+
+### When an IDL already exists
+
+In this case, most of the code remains similar to the previous example, except when an IDL is provided, it supplies the information needed to invoke the service directly:
+
+```typescript
+// set backend server to connect
+// replace with your own backend server url
+const transport = createDubboTransport({
+ baseUrl: "http://localhost:8080",
+});
+// init client
+const client = createPromiseClient(transport);
+
+function App() {
+ // ...
+ // call remote Dubbo service
+ const response = await client.call(
+ "apache.dubbo.demo.example.v1.ExampleService",
+ "say",
+ {
+ sentence: inputValue,
+ });
+}
+```
+
+## Next action
+
+As you progress, creating a server-side application component becomes a crucial step in fleshing out a complete microservices architecture. For further details on this section, please refer to [the documentation](/#todo)
diff --git a/docs/guide/dubboForWEB/SupportedBrowsersandFrameworks.md b/docs/guide/dubboForWEB/SupportedBrowsersandFrameworks.md
index c4dc38b..698ac90 100644
--- a/docs/guide/dubboForWEB/SupportedBrowsersandFrameworks.md
+++ b/docs/guide/dubboForWEB/SupportedBrowsersandFrameworks.md
@@ -1 +1,9 @@
-# SupportedBrowsersandFrameworks
+# Supported browsers and frameworks
+
+Dubbo-JS extends its support to all modern web browsers that embrace the widely implemented Fetch API and Encoding API standards. The library itself, along with the generated codebase, conforms to the ES2017 specification and is fully compatible with TypeScript 5.
+
+Embodying a neutral stance towards frameworks, Dubbo-JS comfortably operates in vanilla JavaScript environments and is equally adept at integrating with popular application and testing frameworks. These include React, Next.js from the React ecosystem, as well as others like Svelte, Vue, Playwright, and Vitest. Additionally, it harmoniously pairs with commonly used package managers such as npm, pnpm, and Yarn, offering immediate usability without additional configuration.
+
+Dubbo-JS also melds seamlessly with various module loaders and bundlers, including esbuild, Vite, and Rollup, catering to diverse development workflows.
+
+While striving for universality, it's worth noting that certain subtleties and common setup challenges may arise based on the specific tooling within your project. This section serves to shed light on these potential issues and presents actionable workarounds with accompanying examples to guide you through configuring Dubbo-JS in your technology stack effectively.
diff --git a/example/dubbo-node-example/package-lock.json b/example/dubbo-node-example/package-lock.json
index ee567f0..2dad4f4 100644
--- a/example/dubbo-node-example/package-lock.json
+++ b/example/dubbo-node-example/package-lock.json
@@ -756,4 +756,4 @@
"integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="
}
}
-}
+}
\ No newline at end of file
diff --git a/example/dubbo-web-example/README.md b/example/dubbo-web-example/README.md
index 40c28fe..c57aea3 100644
--- a/example/dubbo-web-example/README.md
+++ b/example/dubbo-web-example/README.md
@@ -2,11 +2,11 @@
基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2 上。Dubbo TypeScript SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 APl 来发布或调用这些服务。
-[arc](./doc/arc.png)
+
本示例演示了如何使用 dubbo-js 开发运行在浏览器上的 web 应用程序，web 页面将调用 dubbo node.js 开发的后端服务并生成页面内容。本示例演示基于 IDL 和非 IDL 两种编码模式。
-[arc](./doc/web.png)
+
## IDL 模式
@@ -236,8 +236,8 @@
// ...
// call remote Dubbo service
const response = await client.call(
- "apache.dubbo.demo.example.v1.ExampleService",
- "say",
+ "apache.dubbo.demo.example.v1.ExampleService",
+ "say",
{
sentence: inputValue,
});
@@ -248,4 +248,4 @@
```Shell
npm run dev
-```
\ No newline at end of file
+```
diff --git a/example/dubbo-web-example/package-lock.json b/example/dubbo-web-example/package-lock.json
index 7ef70c9..cf430e0 100644
--- a/example/dubbo-web-example/package-lock.json
+++ b/example/dubbo-web-example/package-lock.json
@@ -2502,4 +2502,4 @@
}
}
}
-}
+}
\ No newline at end of file
diff --git a/package.json b/package.json
index 5fe9d63..f581777 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,9 @@
{
"private": true,
"name": "dubbo-js-private-workspace",
+ "scripts": {
+ "prepare": "husky install"
+ },
"workspaces": [
"./packages/dubbo",
"./packages/protoc-gen-apache-dubbo-es",
@@ -18,19 +21,20 @@
"node": ">=16",
"npm": ">=8"
},
- "type": "module",
"engineStrict": true,
"devDependencies": {
- "husky": "^6.0.0",
+ "@commitlint/cli": "^19.2.1",
+ "@commitlint/config-conventional": "^19.1.0",
+ "@types/node": "^20.4.0",
"@typescript-eslint/eslint-plugin": "^5.59.1",
"@typescript-eslint/parser": "^5.59.2",
"eslint": "^8.39.0",
"eslint-import-resolver-typescript": "^3.5.5",
"eslint-plugin-import": "^2.27.5",
"eslint-plugin-node": "^11.1.0",
+ "husky": "^6.0.0",
"prettier": "^2.8.8",
- "typescript": "5.0.3",
- "@types/node": "^20.4.0"
+ "typescript": "5.0.3"
},
"license": "Apache-2.0"
}
