BaudDance Serial Assistant: a serial port tool that lives in a browser tab

The port stays on the user's machine, not on a server

Most serial consoles are native applications, and native applications need an installer, a driver and a platform build. BaudDance Serial Assistant takes a different route. It is described as a serial port assistant that can be used directly in the browser, and the browser compatibility table is blunt about the consequence: Web Serial API works in Chrome 89+ and Edge 89+, Web Bluetooth API works in Chrome 56+ and Edge 79+, and both rows are marked unsupported in Firefox and Safari. The notice under that table says the application needs a browser supporting the Web Serial API and that Chromium based browsers are the main target.

So the project serves a specific audience: people who need to talk to a microcontroller, a pass-through module or a lab instrument from a desktop that already has Chrome or Edge, and who would rather open a URL than install anything. The repository is a Vue 3 project built with Vite and Tailwind CSS 4.x, with the panel structure held in src/components (ActivityBar, ControlPanel, RecordPanel, SendPanel, SettingPanel, StatusBar, TopBar) and the device logic in composables such as useSerial, useBle and useDataCode. package.json marks the package as private and versioned 3.0.1, so the project is shipped as an application rather than as a reusable package.

Two connection paths with different configuration surfaces

The tool supports two transports and they are not interchangeable. The serial path uses the Web Serial API, auto detects available serial devices and exposes baud rate, data bits and stop bits as configuration, with real time sending and receiving shown in the record panel. The Bluetooth path uses the Web Bluetooth API for BLE devices, and it carries a specific piece of domain knowledge: built in configurations for common serial pass-through modules such as DX-BT24 and DX-BT16, plus support for custom 16 bit, 32 bit and 128 bit GATT service, write characteristic and notify characteristic UUIDs. It also picks between write with response and write without response automatically based on the GATT characteristic properties.

That last detail is what separates the two paths in practice. A USB port exposes parameters you type in; a BLE link exposes a characteristic layout that has to match the module's firmware. The alternative to this project is not another tool but the other transport. If your hardware already presents a USB serial port, use the Web Serial path and you avoid GATT UUIDs entirely. If it is a BLE module, the Web Bluetooth path is the only one that works, and you will need to know the module's characteristic layout, which the README says you can type in yourself.

Cloning and running the project locally

The stated prerequisites are Node.js 22 or newer, pnpm 10 or newer (recommended over npm), and a modern browser supporting the Web Serial API. The install path is short:

# 克隆项目
git clone <repository-url>
cd SerialAssistant

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

The clone URL is left as a placeholder in the documentation, so you need the actual repository address from the source you are reading. After pnpm dev the application is served by Vite with hot reload, and after pnpm build the output is a static bundle in dist. The same script list is used later for checks and deployment:

pnpm dev                # 启动开发服务器
pnpm build              # 构建生产版本
pnpm preview            # 预览构建结果
pnpm analyze            # 分析构建包大小
pnpm lint               # 代码检查
pnpm lint:fix           # 自动修复代码问题
pnpm test               # 运行单元测试
pnpm test:run           # 运行单元测试（单次）

Two things are worth knowing before you rely on the scripts. The package.json scripts show test wired to vitest --run and test:w to vitest in watch mode, and lint wired to eslint with an antfu eslint config, so linting and unit tests are wired in even though the documentation does not describe a test suite in depth. The devDependency list also pins pnpm through packageManager as [email protected], and the repository ships pnpm-lock.yaml and a .npmrc, so an npm install would not reproduce the same tree.

Docker serves the same static bundle through nginx

Because the build output is a static site, the container image is a static file server rather than an application server. The Dockerfile has two stages: node:22-slim installs pnpm@10, copies package.json, pnpm-lock.yaml and pnpm-workspace.yaml, runs pnpm install --frozen-lockfile, copies the rest of the tree and runs pnpm build; the runtime stage is nginx:stable-alpine, with the dist directory copied to /usr/share/nginx/html, nginx.conf copied to /etc/nginx/conf.d/default.conf, port 80 exposed and nginx started as the command.

The documented commands are:

# 使用Docker构建镜像
docker build -t serial-assistant .

# 运行容器
docker run -d -p 8080:80 --name serial-assistant serial-assistant

The compose file mirrors that shape, building from the local Dockerfile, publishing 8080:80 and restarting the container unless it is stopped, with a commented block for environment variables such as NODE_ENV=production. After the build, the documentation says you open http://localhost:8080 to use the application.

Keep one thing in mind when you deploy this way. The container publishes the web page, but the serial port belongs to the browser that loads it, on the machine of the person using it. Running the container on a server does not give anyone a remote port on the server, it gives them the console UI and whatever device their own browser can reach.

Netlify and Vercel deploy the same dist folder

Static hosting is the other deployment path, and it is configured down to the build command. For Netlify, the site settings use the build command pnpm build, the publish directory dist and Node version 22, and the CLI route is npm install -g netlify-cli, netlify login, then pnpm deploy:netlify. The repository ships netlify.toml for this. For Vercel, vercel.json holds the build command pnpm run build, the output directory dist, the framework set to Vite, route rewrites for SPA routing, long term caching for static assets and Node.js version 22; the CLI route is npm i -g vercel, vercel login, then pnpm deploy:vercel or vercel --prod. .vercelignore keeps deployment packages smaller, and vercel env add VITE_API_URL is the documented way to add environment variables from the command line.

Both hosting routes are one command away from the same build, and both require a Node 22 build environment. The important caveat for this particular application is the browser restriction rather than the hosting: a page served from Netlify or Vercel still needs a Chromium browser with the Web Serial API, and the documentation states that this application currently supports Chromium based browsers.

The open TODO list describes the current limits

The project publishes its own gap list, and it is more informative than the feature list. Unchecked items include refactoring data processing into a Worker, drawing data curves using custom regular expressions or JavaScript scripts, command line style coloured output similar to \033[30m, keyword colour highlighting, and a cache limit to stop large volumes of data from making the interface sluggish. Checked items include SEO work, a copy button on conversation bubbles, exporting the conversation record to JSON, quick input buttons, arrow key recall of sent history, and search.

Two of those unchecked items matter for evaluation. Because data processing has not moved to a Worker, heavy traffic on a serial link is handled on the main thread, and the missing cache limit is a separate known risk of the interface slowing down. The planned curve plotting also means the tool currently records and displays bytes rather than graphing them, so anyone expecting a scope trace will not find one.

There is a third limitation that sits outside the code. The repository has no GitHub releases at all, so there is no tagged version to install, and the only version marker is the 3.0.1 string in package.json. That makes for an ordinary fork and pull request workflow, but it also means there is no published artefact to pin a deployment to.

MIT licensing and the dependency surface you inherit

The repository carries the MIT licence, and the README displays a licence badge, so the code can be reused, modified and shipped in a closed product. The important cost is not the licence but the dependency list. package.json pulls in a broad set of runtime packages: Vue, vue-router, VueUse, Tailwind CSS 4, shadcn style primitives from reka-ui and class-variance-authority, a terminal renderer in @xterm/xterm with its fit addon, uplot for plotting, @tanstack/vue-table and @tanstack/vue-virtual, zod with vee-validate for form validation, fuse.js for fuzzy search, str2gbk for encoding, dayjs for dates and lucide-vue-next for icons. The devDependencies add ESLint 9 with the antfu config, Vitest, jsdom, the Netlify CLI and tooling for git hooks.

Two of those deserve a second look before you adopt the project. The terminal emulator in @xterm/xterm explains the presence of the planned ANSI colour output, since the rendering side is already in place even though the parsing of escape sequences is still an open TODO. And the uplot dependency suggests the data curve work has a rendering library chosen already. Both facts point the same way: the author intends the plotting and colour features to land in this codebase rather than in a rewrite, which makes the TODO list a roadmap you can wait on rather than a sign of abandoned work.

Editorial conclusion

Adopt BaudDance Serial Assistant when the target machines are Chromium desktops and the goal is a zero-install serial console for a lab, a kiosk, or a shared demo machine, and accept that the project ships no GitHub releases and keeps data processing on the main thread. Skip it for Firefox or Safari users, for embedded work that needs the data curve plotting still marked as an open TODO, or for teams that need a tagged artefact. Verify first that your device appears under the Web Serial API on the machine you will actually deploy to, then confirm the pnpm dev workflow before building any Docker image around it.

Frequently asked questions

Official sources

1. BaudDance/SerialAssistant on GitHub
2. Issues
3. License: MIT
4. README