Skip to content

docs: add npm registry note for OpenCode #586

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ding113 merged 1 commit into from
Jan 10, 2026
Merged

docs: add npm registry note for OpenCode #586

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion messages/en/usage.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,8 @@

"npm": {
"title": "Option 3: npm",
"description": "Install globally via npm:"
"description": "Install globally via npm:",
"note": "Note: Avoid installing opencode-ai via npm mirror registries. Mirror registries may cause missing dependencies; use the official npm registry if you hit issues."
},

"bun": {
Expand Down
3 changes: 2 additions & 1 deletion messages/ja/usage.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,8 @@

"npm": {
"title": "方法3：npm",
"description": "npm でグローバルにインストール："
"description": "npm でグローバルにインストール：",
"note": "注: opencode-ai を npm のミラー（サードパーティ registry）経由でインストールするのは推奨しません。依存関係が欠ける場合があるため、問題が出たら公式 npm registry を使用してください。"
},

"bun": {
Expand Down
3 changes: 2 additions & 1 deletion messages/ru/usage.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,8 @@

"npm": {
"title": "Способ 3: npm",
"description": "Глобальная установка через npm:"
"description": "Глобальная установка через npm:",
"note": "Примечание: не рекомендуем устанавливать opencode-ai через npm-зеркала (сторонние registry). В зеркалах могут отсутствовать зависимости; при проблемах используйте официальный npm registry."
},

"bun": {
Expand Down
3 changes: 2 additions & 1 deletion messages/zh-CN/usage.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,7 +503,8 @@

"npm": {
"title": "方式三：npm",
"description": "也可以通过 npm 全局安装："
"description": "也可以通过 npm 全局安装：",
"note": "提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。"
},

"bun": {
Expand Down
3 changes: 2 additions & 1 deletion messages/zh-TW/usage.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,7 +503,8 @@

"npm": {
"title": "方式三：npm",
"description": "也可以通過 npm 全局安裝："
"description": "也可以通過 npm 全局安裝：",
"note": "提示：不建議透過 npm 鏡像源/第三方 registry 安裝 opencode-ai，可能會導致依賴缺失；如遇問題請改用官方 npm registry。"
},

"bun": {
Expand Down
2 changes: 2 additions & 0 deletions src/app/[locale]/usage-doc/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -996,6 +996,7 @@ gemini`}
<CodeBlock language="powershell" code={`npm install -g opencode-ai`} />
</div>

<p className="text-sm text-muted-foreground">{t("opencode.installation.npm.note")}</p>
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While this change is correct, I noticed that the entire npm installation section, including this new note, is duplicated for Windows (here) and for macOS/Linux (around line 1049). This duplication can make future updates more difficult and error-prone.

To improve maintainability, consider refactoring the npm installation UI into a separate component that accepts the shell language (powershell or bash) as a prop. This would centralize the logic and markup for this section.

For example:

const NpmInstallSection = ({ lang }: { lang: 'powershell' | 'bash' }) => {
  const t = useTranslations("usage");
  return (
    <>
      <div className="space-y-3">
        <h5 className="font-semibold text-foreground">
          {t("opencode.installation.npm.title")}
        </h5>
        <p>{t("opencode.installation.npm.description")}</p>
        <CodeBlock language={lang} code={'npm install -g opencode-ai'} />
      </div>
      <p className="text-sm text-muted-foreground">{t("opencode.installation.npm.note")}</p>
    </>
  );
}

While a full refactor is outside the scope of this PR, it's a good improvement to keep in mind for the future.

<p className="text-sm text-muted-foreground">{t("opencode.installation.windows.note")}</p>
</div>
);
Expand Down Expand Up @@ -1045,6 +1046,7 @@ gemini`}
<CodeBlock language="bash" code={`npm install -g opencode-ai`} />
</div>

<p className="text-sm text-muted-foreground">{t("opencode.installation.npm.note")}</p>
<div className="space-y-3">
<h5 className="font-semibold text-foreground">{t("opencode.installation.bun.title")}</h5>
<p>{t("opencode.installation.bun.description")}</p>
Expand Down
2 changes: 2 additions & 0 deletions tests/unit/usage-doc/opencode-usage-doc.test.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ describe("UsageDoc - OpenCode 配置教程", () => {

expect(text).toContain("curl -fsSL https://opencode.ai/install | bash");
expect(text).toContain("npm install -g opencode-ai");
expect(text).toContain("npm mirror registries");
expect(text).toContain("bun add -g opencode-ai");
expect(text).toContain("brew install anomalyco/tap/opencode");
expect(text).toContain("paru -S opencode-bin");
Expand All @@ -112,6 +113,7 @@ describe("UsageDoc - OpenCode 配置教程", () => {
expect(usageMessages).toHaveProperty("opencode.installation.title");
expect(usageMessages).toHaveProperty("opencode.installation.script.title");
expect(usageMessages).toHaveProperty("opencode.installation.npm.title");
expect(usageMessages).toHaveProperty("opencode.installation.npm.note");
expect(usageMessages).toHaveProperty("opencode.installation.bun.title");
expect(usageMessages).toHaveProperty("opencode.installation.macos.homebrew.title");
expect(usageMessages).toHaveProperty("opencode.installation.linux.homebrew.title");
Expand Down
7 changes: 6 additions & 1 deletion tests/unit/usage-doc/usage-doc-page.test.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,10 @@ describe("UsageDocPage - 目录/快速链接交互", () => {
writable: true,
});

document.cookie = "auth-token=test-token";
Object.defineProperty(document, "cookie", {
configurable: true,
get: () => "auth-token=test-token",
});
Comment on lines +65 to +68
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using Object.defineProperty is a good improvement for mocking document.cookie. To make the test more idiomatic with Vitest, consider using vi.spyOn. It provides a clear API for mocking and restoring spies. You can then replace the manual cleanup on line 80 with cookieSpy.mockRestore().

    const cookieSpy = vi
      .spyOn(document, "cookie", "get")
      .mockReturnValue("auth-token=test-token");


const { unmount } = await renderWithIntl("en", <UsageDocPage />);

Expand All @@ -73,6 +76,8 @@ describe("UsageDocPage - 目录/快速链接交互", () => {
expect(dashboardLink).not.toBeNull();

await unmount();

Reflect.deleteProperty(document, "cookie");
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

If you adopt the vi.spyOn approach suggested for lines 65-68, this manual cleanup can be replaced with a call to cookieSpy.mockRestore() for better consistency with Vitest's testing patterns.

    cookieSpy.mockRestore();

});

test("目录项点击后应触发平滑滚动", async () => {
Expand Down
Loading