# cccdev drops a devtools panel into the Cocos Creator browser preview

> cccdev is a small CLI that installs a preview template into a Cocos Creator project so the browser preview gains a runtime node tree, live property editing and a profiler panel. The implementation is deliberately tiny: a Bun TypeScript CLI with no runtime dependencies and a Preact panel of about 3KB.

**potato47/ccc-devtools** — Cocos Creator 网页调试工具，运行时查看、修改节点树，实时更新节点属性，可视化显示缓存资源。

- Repository: https://github.com/potato47/ccc-devtools
- Stars: 1,275 · Forks: 393
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/potato47-ccc-devtools

## The tool is a template installer, not a library

The project is named cccdev and it is distributed as the `cccdev` package on npm at version 1.0.3. What it does is narrow: it installs a preview template into a Cocos Creator project so the browser preview gains a set of development tools. The listed features are a real-time node tree browser, synchronized editing of node properties, a way to output node and component references to the console, a marker for UI node positions, a separate debug information panel for things like FPS, and profiler performance analysis. The package description says it plainly: a CLI tool for installing the Cocos Creator devtools preview template. The console reference output is a small but telling detail, because it is the bridge between the graphical panel and the rest of your debugging habits, since a reference you can paste into a console is often more useful than a value you can only read.

## One command installs it into the project

The usage instructions are to run the command in the root of the Cocos Creator project, and the recommendation is to use npx or bunx with the latest tag so you always get the current version:

```bash
# 推荐: 通过 npx/bunx 始终使用最新版本
npx cccdev@latest init

# 或
bunx cccdev@latest init
```

There is a force flag for when you want to overwrite an existing `preview-template/` directory, which is the only destructive thing the tool can do:

```bash
npx cccdev@latest init --force
```

After that you refresh the browser preview and the devtools are available. The CLI detects the Cocos Creator version automatically, so there is no version flag to pass, and the output shows what it did:

```
$ npx cccdev@latest init

  检测到 Cocos Creator 3.x 项目

  ✓ 模板安装成功!

  preview-template/
    index.ejs
    devtools/
      assets/
        index.js
        style.css

  刷新浏览器预览即可使用 devtools。
```

The template directory contains an `index.ejs` file and a `devtools/assets/` directory holding the panel's JavaScript and CSS, which tells you the mechanism: the tool replaces the preview template that Cocos Creator uses for its browser preview with one that also loads the panel.

## The CLI surface is one command and three flags

The options block is short enough to reproduce in full:

```
Usage: cccdev <command> [options]

Commands:
  init          安装 devtools 预览模板到 Cocos Creator 项目

Options:
  --help, -h    显示帮助
  --version     显示版本号
  --force       覆盖已存在的 preview-template
```

One command, three flags, and a single behaviour: install the preview template. There is no configuration file, no daemon and no background process, which is the design constraint that shapes everything else. The project also documents a local development path, so you can test a modified template in a real project without publishing:

```bash
cd /path/to/cocos-project
bun run /path/to/ccc-devtools/bin/cccdev.ts init
```

That runs the CLI entry point directly with Bun against a checkout of the tool, which is the loop a contributor works in.

## The panel is a Preact app of about 3KB

The technical stack is listed at the end of the documentation and it is where the project's ambitions are visible. The view layer is Preact plus Signals, with a runtime of roughly 3KB, the build is Vite in IIFE library mode, and the CLI is executed natively as TypeScript by Bun with zero runtime dependencies. That last point is the reason the CLI is pleasant to use: because Bun runs the TypeScript directly, there is no compiled JavaScript to ship and nothing for npm to install at run time, which is why the published files are only `bin/`, `src/` and `template/`. The 3KB Preact runtime is the other number worth holding on to, because a debug panel that is small enough to be invisible in the bundle is a panel you can leave enabled while you work.

## The template source is private and the output is checked in

The project structure shows an arrangement that explains how the package is built:

```
ccc-devtools/
├── bin/cccdev.ts                   # CLI 入口
├── src/
│   ├── cli.ts                      # 命令路由
│   ├── commands/init.ts            # cccdev init 实现
│   └── utils/                      # detect, logger
├── template/                       # 构建产物 (gitignored, 发布时打入包)
│   └── 3x/
├── packages/
│   └── cccdev-template-3x/          # CC 3.x 模板源码 (private, 不发布)
│       ├── src/                    # Preact 源码
│       ├── template/               # vite 构建输出
│       └── vite.config.ts          # IIFE 构建配置
```

The template directory holds the build output and is gitignored, but it is packed into the published npm tarball. The actual Preact source lives in a packages directory marked as private and not published, which means you can install the tool and use the panel, but you cannot read the panel's source from npm, only from the repository. The build script copies the Vite output into the template directory, and the directory is named for the Cocos Creator major version, so the versioning is per generator generation rather than per release.

## Bun is the toolchain, with oxlint and oxfmt

Development requires Bun 1.0 or newer, and the dependency install is a single command in the template package:

```bash
cd packages/cccdev-template-3x && bun install
```

The scripts are a modern set: `bun run build` builds the template and copies it to the template directory, `bun run type-check` runs a TypeScript type check over the root CLI code, `bun run lint` and `bun run lint:fix` run oxlint, and `bun run fmt` and `bun run fmt:check` run oxfmt, the formatter, with a check mode that does not write. The linting and formatting tools are both from the oxc project rather than the older eslint and prettier combination, and the configuration lives in `.oxfmtrc.json` at the root. The dev dependencies are minimal: the type definitions for Bun, oxfmt, oxlint and TypeScript itself. The publish step is a build followed by `npm publish`.

## What you get and what you do not

It is worth being clear about what this tool is not. It is not a debug mode inside the Cocos Creator editor, and it does not attach to a running process. It replaces the preview template, so everything it can do is scoped to what the browser preview can see and change at runtime. That is a real limit for debugging anything that happens before the preview loads, and a real strength for everything after it, since the scene graph in the preview is the scene graph that is running. The documentation also links the Cocos Creator documentation on customising the web preview and the Cocos Creator plugin store, where an identical product is listed, with the note that the store version exists to support the author's own work. The licence is MIT, the most recent tagged releases are v3.5.0 from 2022-07-17 and v3.0.0 from 2022-01-01, and the last push to the master branch was on 2026-04-05.

## Conclusion

Adopt cccdev if you work in Cocos Creator and want to inspect and edit the running scene tree from the browser preview rather than by adding console logs, since the tool gives you a live node tree, editable properties and a profiler without touching game code. Do not adopt it as a replacement for a full debugging workflow, since it is a preview template rather than a debugger attached to the editor. Verify first which Cocos Creator version the CLI detects in your project, that the template directory is not already carrying changes you care about before using the force flag, and that the panel's runtime footprint is acceptable for your target platform.

## FAQ

### How do I install cccdev in a Cocos Creator project?

Run `npx cccdev@latest init` or `bunx cccdev@latest init` in the root of the project. The CLI detects the Cocos Creator version, installs the devtools template into `preview-template/`, and you then refresh the browser preview.

### What does cccdev add to the Cocos Creator browser preview?

A real-time node tree browser, synchronized editing of node properties, output of node and component references to the console, UI node position markers, a separate debug information panel showing FPS, and profiler performance analysis.

### What are the options for the cccdev command?

There is one command, `init`, which installs the devtools preview template. The options are `--help` and `-h` for help, `--version` to print the version, and `--force` to overwrite an existing preview-template directory.

### What does the cccdev panel cost in bundle size?

The view layer is Preact with Signals, about a 3KB runtime, built with Vite in IIFE library mode. The CLI itself is executed natively as TypeScript by Bun with zero runtime dependencies, so nothing is installed when you run it through npx or bunx.

### How do I test a local change to the cccdev template?

Run the CLI entry point directly from your checkout against a real project with `bun run /path/to/ccc-devtools/bin/cccdev.ts init`. The panel source lives in a private packages directory that is not published to npm, so the repository is where you work on it.

## Sources

- [Issues](https://github.com/potato47/ccc-devtools/issues)
- [License: MIT](https://github.com/potato47/ccc-devtools/blob/master/LICENSE)
- [potato47/ccc-devtools on GitHub](https://github.com/potato47/ccc-devtools)
- [README](https://github.com/potato47/ccc-devtools/blob/master/README.md)
- [Releases](https://github.com/potato47/ccc-devtools/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/potato47-ccc-devtools