Setup Guide

Back

Copy for AI Assistant 复制给 AI 助手

Copy this guide as a prompt — paste it into ChatGPT, Claude, or Cursor to get step-by-step help. 将本指南复制为提示词，粘贴到 ChatGPT、Claude 或 Cursor 中，让 AI 一步步指导你完成配置。

Quick Start

Already have your token? Run these 3 commands:

Terminal
# 1. Set your token as environment variable export NPM_TOKEN="your-token-here" # 2. Add .npmrc to your project root echo '@talespark:registry=https://registry.talespark.com/ //registry.talespark.com/:_authToken=${NPM_TOKEN}' > .npmrc # 3. Verify npm whoami --registry=https://registry.talespark.com/

Windows users: see Step 1 below for PowerShell equivalent. For detailed instructions, read on.

Prerequisites

  • Node.js (v16+) and npm installed
  • A Talespark Registry account — Register with an invite code
  • Your auth token — Get Token

npm / TypeScript Project Setup

1

Configure .npmrc (Recommended)

Create .npmrc in your project root:

your-project/.npmrc
@talespark:registry=https://registry.talespark.com/ //registry.talespark.com/:_authToken=${NPM_TOKEN}

Set the NPM_TOKEN environment variable:

macOS / Linux (~/.bashrc or ~/.zshrc)
export NPM_TOKEN="your-token-here"
Windows (PowerShell)
[System.Environment]::SetEnvironmentVariable("NPM_TOKEN", "your-token-here", "User")
This keeps your token out of git. Commit .npmrc to the project — it only references ${NPM_TOKEN}, not the actual secret.
2

Alternative: User-level .npmrc

Add the token directly to ~/.npmrc (your home directory, never committed):

~/.npmrc
@talespark:registry=https://registry.talespark.com/ //registry.talespark.com/:_authToken=your-token-here
Never commit a file containing your actual token.
3

Alternative: npm login

Authenticate interactively — this auto-updates ~/.npmrc:

Terminal
npm login --registry=https://registry.talespark.com/
4

Install Packages

Terminal
npm install @talespark/your-package-name

@talespark/* packages come from the private registry. Everything else uses the public npm registry.

5

Verify

Terminal
npm whoami --registry=https://registry.talespark.com/

Should print your registry username.

Unity UPM Setup

1

Configure .upmconfig.toml

Create this file in your home directory:

  • Windows: %USERPROFILE%\.upmconfig.toml
  • macOS / Linux: ~/.upmconfig.toml
~/.upmconfig.toml
[npmAuth."https://registry.talespark.com"] token = "your-token-here"
2

Add Scoped Registry to manifest.json

Edit Packages/manifest.json in your Unity project:

Packages/manifest.json
{ "scopedRegistries": [ { "name": "Talespark", "url": "https://registry.talespark.com/", "scopes": ["com.talespark"] } ], "dependencies": { "com.talespark.your-package": "1.0.0" } }
3

Install via Package Manager

In Unity: Window > Package Manager, then + > Add package by name.

CI/CD Setup

1

GitHub Actions

Add NPM_TOKEN in repo Settings > Secrets, then:

.github/workflows/ci.yml
- name: Install dependencies run: npm ci env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Requires project-level .npmrc with ${NPM_TOKEN} (see Step 1).

Troubleshooting

  • 401 Unauthorized — Token expired or wrong. Regenerate here.
  • 404 Not Found — Check scope: @talespark/ for npm, com.talespark. for Unity.
  • Unable to authenticate — Verify NPM_TOKEN env var is set and shell has been restarted.
  • SELF_SIGNED_CERT — Don't set strict-ssl=false. Contact admin.

Token validity: 365 days. Refresh anytime at Get Token.

快速开始

已有 Token？执行以下 3 条命令即可：

终端
# 1. 设置 Token 环境变量 export NPM_TOKEN="你的token" # 2. 在项目根目录创建 .npmrc echo '@talespark:registry=https://registry.talespark.com/ //registry.talespark.com/:_authToken=${NPM_TOKEN}' > .npmrc # 3. 验证 npm whoami --registry=https://registry.talespark.com/

Windows 用户请看下方步骤 1 的 PowerShell 命令。详细说明请继续阅读。

前置条件

  • 已安装 Node.js（v16+）和 npm
  • 已注册 Talespark Registry 账号 — 通过邀请码 注册
  • 已获取认证 Token — 获取 Token

npm / TypeScript 项目配置

1

配置 .npmrc（推荐）

在项目根目录创建 .npmrc：

your-project/.npmrc
@talespark:registry=https://registry.talespark.com/ //registry.talespark.com/:_authToken=${NPM_TOKEN}

设置 NPM_TOKEN 环境变量：

macOS / Linux（~/.bashrc 或 ~/.zshrc）
export NPM_TOKEN="你的token"
Windows（PowerShell）
[System.Environment]::SetEnvironmentVariable("NPM_TOKEN", "你的token", "User")
Token 通过环境变量引用，不会提交到 git。.npmrc 可以提交到仓库，但 Token 本身不能。
2

备选：写入用户级 .npmrc

将 Token 直接写入 ~/.npmrc（主目录，不会被 git 追踪）：

~/.npmrc
@talespark:registry=https://registry.talespark.com/ //registry.talespark.com/:_authToken=你的token
切勿将包含真实 Token 的文件提交到 git。
3

备选：npm login 交互登录

交互式登录，会自动更新 ~/.npmrc：

终端
npm login --registry=https://registry.talespark.com/
4

安装包

终端
npm install @talespark/你的包名

@talespark/* 从私有 registry 拉取，其他包仍从公共 npm 获取。

5

验证

终端
npm whoami --registry=https://registry.talespark.com/

应输出你的 registry 用户名。

Unity UPM 配置

1

配置 .upmconfig.toml

在用户主目录创建此文件：

  • Windows: %USERPROFILE%\.upmconfig.toml
  • macOS / Linux: ~/.upmconfig.toml
~/.upmconfig.toml
[npmAuth."https://registry.talespark.com"] token = "你的token"
2

在 manifest.json 中添加 Scoped Registry

编辑 Unity 项目的 Packages/manifest.json：

Packages/manifest.json
{ "scopedRegistries": [ { "name": "Talespark", "url": "https://registry.talespark.com/", "scopes": ["com.talespark"] } ], "dependencies": { "com.talespark.你的包名": "1.0.0" } }
3

通过 Package Manager 安装

Unity 中：Window > Package Manager，点击 + > Add package by name。

CI/CD 配置

1

GitHub Actions

在仓库 Settings > Secrets 添加 NPM_TOKEN：

.github/workflows/ci.yml
- name: Install dependencies run: npm ci env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

需要项目级 .npmrc 使用 ${NPM_TOKEN} 变量（见步骤 1）。

常见问题排查

  • 401 Unauthorized — Token 过期或错误，重新生成。
  • 404 Not Found — 检查作用域：npm 用 @talespark/，Unity 用 com.talespark.。
  • Unable to authenticate — 确认 NPM_TOKEN 已设置且终端已重启。
  • SELF_SIGNED_CERT — 请勿设 strict-ssl=false，联系管理员。

Token 有效期：365 天，可随时到 获取 Token 刷新。

registry.talespark.com