vitadeck-deck-app-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize a Deck App (standalone)

初始化独立Deck App

What is a Deck App?

什么是Deck App？

A Deck App is a user-authored interactive experience that runs on VitaDeck on PlayStation Vita (or the desktop host). You write it in React against the VitaDeck Runtime API (

@vitadeck/sdk

components like

Screen

Text

Button

At build time, the SDK compiles your Deck App Source Entry (

src/App.tsx

by default) into a Deck App Package — a portable

.vdapp

folder (plus a

.vdapp.zip

archive for upload). The package contains your compiled app and metadata; VitaDeck supplies React and the runtime on device.

This workflow assumes a standalone project anywhere on disk, using the published npm package — not the VitaDeck monorepo.

Deck App是由用户编写的交互式体验应用，可在PlayStation Vita（或桌面主机）上的VitaDeck中运行。你可以使用React基于VitaDeck Runtime API（

@vitadeck/sdk

提供的

Screen

、

Text

、

Button

等组件）进行开发。

在构建阶段，SDK会将你的Deck App源码入口（默认是

src/App.tsx

）编译成Deck App包——一个可移植的

.vdapp

文件夹（以及用于上传的

.vdapp.zip

压缩包）。该包包含编译后的应用和元数据；VitaDeck会在设备端提供React和运行时环境。

本工作流适用于磁盘任意位置的独立项目，使用已发布的npm包——而非VitaDeck单仓库。

Prerequisites

前置条件

Node.js 22+
npm, pnpm, or Bun
VitaDeck installed on Vita (or desktop host) to run the built package

Node.js 22+
npm、pnpm或Bun
VitaDeck已安装在Vita设备上（或桌面主机），用于运行构建后的包

Quick start

快速开始

From the directory where the new project should live:

npx @vitadeck/sdk create my-deck-app
cd my-deck-app
npm install

Edit

src/App.tsx

— the default export is your Deck App Component (root UI for the full Vita display).

Build:

npx @vitadeck/sdk build

在要创建新项目的目录下执行：

npx @vitadeck/sdk create my-deck-app
cd my-deck-app
npm install

编辑

src/App.tsx

——默认导出的是你的Deck App组件（适配Vita全屏显示的根UI）。

构建：

npx @vitadeck/sdk build

or: npm run build

或：npm run build


Outputs under `dist/` (from `vitadeck.config.json`):

- `dist/<slug>.vdapp/` — unpacked **Deck App Package**
- `dist/<slug>.vdapp.zip` — **Runtime Upload Archive** for LAN publish

The `<slug>` is derived from the project `name` in `vitadeck.config.json` (e.g. `my-deck-app` → `my-deck-app.vdapp`).


输出文件位于`dist/`目录下（配置来自`vitadeck.config.json`）：

- `dist/<slug>.vdapp/` —— 解压后的**Deck App包**
- `dist/<slug>.vdapp.zip` —— 用于局域网发布的**运行时上传压缩包**

`<slug>`由`vitadeck.config.json`中的项目`name`派生而来（例如`my-deck-app` → `my-deck-app.vdapp`）。

What

create

generates

create

命令生成的文件

File	Purpose
`vitadeck.config.json`	Deck App manifest: `name` , `entry` , `outDir`
`package.json`	Pins `@vitadeck/sdk` ( `^` matching scaffold version), React 18.3.x
`src/App.tsx`	Deck App Source Entry — default-exported root component
`src/vitadeck-env.d.ts`	TypeScript env for Deck App globals
`tsconfig.json`	Extends `@vitadeck/sdk/tsconfig`

Optional

vitadeck.config.json

fields:

version

(overrides

package.json

semver in the built manifest),

fonts

(named font files copied into the package).

文件	用途
`vitadeck.config.json`	Deck App清单：包含 `name` 、 `entry` 、 `outDir` 等配置
`package.json`	固定 `@vitadeck/sdk` 版本（与脚手架版本 `^` 匹配），React版本为18.3.x
`src/App.tsx`	Deck App源码入口——默认导出的根组件
`src/vitadeck-env.d.ts`	Deck App全局变量的TypeScript环境声明文件
`tsconfig.json`	继承 `@vitadeck/sdk/tsconfig` 配置

vitadeck.config.json

的可选字段：

version

（覆盖构建后清单中

package.json

的语义化版本）、

fonts

（复制到包中的指定字体文件）。

After scaffolding

脚手架搭建完成后

Typecheck:
```
npx tsc
```
or
```
npm run tsc
```
Iterate: edit
```
src/App.tsx
```
, rebuild with
```
npx @vitadeck/sdk build
```
Skip zip:
```
npx @vitadeck/sdk build --no-zip
```
when only the
```
.vdapp
```
folder is needed
Deploy to Vita: upload
```
dist/*.vdapp.zip
```
via Runtime Upload — see vitadeck-vdapp-upload

类型检查：执行
```
npx tsc
```
或
```
npm run tsc
```
迭代开发：编辑
```
src/App.tsx
```
，执行
```
npx @vitadeck/sdk build
```
重新构建
跳过压缩：当仅需要
```
.vdapp
```
文件夹时，执行
```
npx @vitadeck/sdk build --no-zip
```
部署到Vita设备：通过运行时上传功能上传
```
dist/*.vdapp.zip
```
——详见vitadeck-vdapp-upload

Requirements and constraints

要求与限制

React 18.3.x — peer dependency; build fails if another major/minor is resolved
Entry must default-export one React component; do not call VitaDeck registration APIs — the SDK generates that

Package version in the built

manifest.json

comes from

package.json

version

unless

vitadeck.config.json

sets

version

React 18.3.x —— 对等依赖；如果解析到其他主版本/次版本，构建会失败
入口文件必须默认导出一个React组件；不要调用VitaDeck注册API——SDK会自动生成相关代码
构建后
```
manifest.json
```
中的包版本来自
```
package.json
```
的
```
version
```
字段，除非
```
vitadeck.config.json
```
设置了
```
version
```
字段

Troubleshooting

故障排除

Usage: vitadeck create <project-name>
— pass a project folder name:

npx @vitadeck/sdk create my-app

Target directory already exists — pick a new name or remove the existing folder
React version error — ensure
```
react
```
is
```
18.3.x
```
in
```
package.json
```
, then reinstall
Wrong context — inside the VitaDeck monorepo, examples live under
```
js/examples/
```
and use workspace linking; this skill is for external projects only

Usage: vitadeck create <project-name>
—— 需要传入项目文件夹名称：

npx @vitadeck/sdk create my-app

目标目录已存在 —— 选择新名称或删除现有文件夹
React版本错误 —— 确保
```
package.json
```
中
```
react
```
版本为
```
18.3.x
```
，然后重新安装依赖
上下文错误 —— 在VitaDeck单仓库内，示例项目位于
```
js/examples/
```
并使用工作区链接；本指南仅适用于外部项目

链接

npm: @vitadeck/sdk
SDK readme: js/packages/sdk/README.md

npm：@vitadeck/sdk
SDK说明文档：js/packages/sdk/README.md

vitadeck-deck-app-init

Original

Translation

Initialize a Deck App (standalone)

初始化独立Deck App

What is a Deck App?

什么是Deck App？

Prerequisites

前置条件

Quick start

快速开始

or: npm run build

或：npm run build

What
`create`
generates

`create`
命令生成的文件

After scaffolding

脚手架搭建完成后

Requirements and constraints

要求与限制

Troubleshooting

故障排除

Links

链接

vitadeck-deck-app-init

Original

Translation

Initialize a Deck App (standalone)

初始化独立Deck App

What is a Deck App?

什么是Deck App？

Prerequisites

前置条件

Quick start

快速开始

or: npm run build

或：npm run build

What create generates

create命令生成的文件

After scaffolding

脚手架搭建完成后

Requirements and constraints

要求与限制

Troubleshooting

故障排除

Links

链接

What
`create`
generates

`create`
命令生成的文件