Integration docs

[yamcodes]

Summary by CodeRabbit

• New Features

  • Introduced a reusable Badge UI component.
  • Improved docs navigation with dynamic icons and a visible “New” badge where applicable.

• Documentation

  • Added an Integrations section with new pages for VS Code & Cursor and JetBrains IDEs.
  • Removed the outdated “Import Options” guide and adjusted docs titles/structure.

• Chores

  • Added a repository-wide fix script.
  • Updated development dependencies to support docs and styling workflows.

[changeset-bot]

⚠️ No Changeset found

Latest commit: ab27b15

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
arkenv	Ready	Preview	Comment	Sep 12, 2025 11:36am

[coderabbitai]

Walkthrough

Introduces a new Badge UI component, replaces the docs source module with a TSX version that renders icons (including a “New” badge) via a centralized handler, adds new Integrations docs for VS Code and JetBrains, removes/updates some Guides and meta entries, deletes an obsolete source file, and updates package.json scripts/devDeps.

Changes

Cohort / File(s)	Summary
UI Component: Badge apps/www/components/ui/badge.tsx	Adds a Badge component using cva with variants: default, secondary, destructive, outline; exports badgeVariants, BadgeProps, and Badge.
Docs Source Integration apps/www/lib/source.tsx, apps/www/lib/source.ts	Replaces source.ts with source.tsx; new icon handler supports lucide-react icons, a "New" sentinel that renders a Badge, undefined for no icon, and throws on invalid names; exports IconName type and source.
Docs: Integrations apps/www/content/docs/integrations/vscode.mdx, apps/www/content/docs/integrations/jetbrains.mdx	Adds new integration pages for VS Code/Cursor and JetBrains with examples and links.
Docs: Guides and Titles apps/www/content/docs/guides/import-options.mdx, apps/www/content/docs/guides/type-function.mdx	Removes the Import Options guide; retitles “Type Function” to “type function”.
Docs Navigation Meta apps/www/content/docs/meta.json	Inserts a new “Integrations” section with VS Code & Cursor and JetBrains entries; removes guides/import-options and guides/type-function from pages array.
Tooling apps/www/package.json	Adds a fix script and devDependencies: @ark/util, @tailwindcss/postcss, @types/mdx.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant User as User
  participant Docs as Docs UI
  participant Loader as loader("/docs")
  participant Src as source.icon(icon?: IconName)
  participant Lucide as lucide-react icons
  participant Badge as <Badge/>

  User->>Docs: Navigate to docs page
  Docs->>Loader: Resolve page metadata (with optional icon)
  Loader->>Src: icon(iconName?)
  alt No icon name provided
    Src-->>Loader: undefined
  else Icon is lucide-react key
    Src->>Lucide: Lookup component by name
    Lucide-->>Src: Icon component
    Src-->>Loader: ReactElement(Icon)
  else Icon is "New"
    Src->>Badge: Create <Badge variant="secondary" ...>new</Badge>
    Badge-->>Src: ReactElement(Badge)
    Src-->>Loader: ReactElement(Badge)
  else Invalid icon name
    Src-->>Loader: throw Error("icon is not a valid IconName")
  end
  Loader-->>Docs: Page data with icon element (or none)
  Docs-->>User: Render page with icon/badge

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Add ArkThemes to "Integrating with VS Code" guide #152 — Adds VS Code integrations documentation and mentions ArkThemes, aligning with the issue’s request.

Possibly related PRs

• Export createEnv as the default export #136 — Also modifies docs icon handling; this PR supersedes the prior helper by introducing a typed IconName and Badge-based “New” rendering.

Pre-merge checks (3 passed)

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "Integration docs" is concise and directly describes the primary change in this PR—adding integrations documentation and updating the docs metadata; it accurately signals the main purpose to reviewers while remaining short and readable. Although the changes include supporting code (new Badge component, source.tsx) and package updates, the title is not misleading and focuses on the dominant intent.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

Poem

Hopping through docs with a bright, shiny hue,
I stamped a “new” badge—sparkling, true.
VS Code and JetBrains, paths now aligned,
Icons behave, sharply defined.
With scripts tidied up and pages in view,
This bunny ships pixels—swift as the dew. 🐇✨

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch integration-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[yamcodes]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (7)

apps/www/content/docs/guides/type-function.mdx (1)

2-2: Title casing: confirm style guide consistency.

You switched to sentence case (“type function”). Other pages (e.g., “Quickstart”) appear Title Case. Confirm the intended docs style and align accordingly.

apps/www/content/docs/integrations/jetbrains.mdx (1)

1-26: JetBrains link looks correct; consider adding quick install steps and IDE scope.

The marketplace link is valid. Consider adding a one‑liner with install steps (Settings/Preferences → Plugins → Marketplace → “ArkType”) and clarifying supported IDEs (IntelliJ IDEA, WebStorm, etc.) for discoverability.

Reference: JetBrains Marketplace page for the plugin. (jetbrains.com)

apps/www/content/docs/integrations/vscode.mdx (1)

2-4: Cursor mention: optional clarifier.

Since the title says “VS Code & Cursor,” consider a note that Cursor supports VS Code extensions and the same ArkType extension works there too.

Also applies to: 16-25

apps/www/content/docs/meta.json (1)

3-12: Navigation change: confirm orphaned page intent.

You removed guides/type-function from nav while the file still exists (title updated). Confirm this is intentional (discoverable via direct URL but not surfaced), or remove the file to avoid stale content.

apps/www/lib/source.tsx (2)

27-33: Type safety and future‑proofing for icon resolution.

Avoid as never, check the “New” sentinel first, and use Object.hasOwn for robustness. Optionally fail open in prod to prevent docs crashes.

Apply:

-    if (icon in icons) return createElement(icons[icon as never]);
-    if (icon === "New")
-      return <Badge className="h-4 text-[10px] px-[0.2rem] order-2">new</Badge>;
-
-    throw new Error(`${icon} is not a valid icon`);
+    if (icon === "New") {
+      return <Badge className="h-4 text-[10px] px-[0.2rem] order-2">new</Badge>;
+    }
+    if (icon && Object.hasOwn(icons, icon as string)) {
+      const LucideIcon = icons[icon as keyof typeof icons];
+      return createElement(LucideIcon);
+    }
+    // Prefer not to crash the page in production
+    if (process.env.NODE_ENV !== "production") {
+      throw new Error(`${String(icon)} is not a valid icon`);
+    }
+    return undefined;

---

8-18: Remove dead commented code.

Drop the old createNewElement block—source of truth is the Badge path now.

-// function createNewElement() {
-// 	return createElement(
-// 		"span",
-// 		{
-// 			className:
-// 				"bg-gradient-to-r from-yellow-400 to-yellow-100 text-amber-800 px-1.5 py-0.5 rounded text-xs font-medium",
-// 			"data-new": "true",
-// 		},
-// 		"New",
-// 	);
-// }

apps/www/components/ui/badge.tsx (1)

25-31: Use a span for inline semantics.

Badge is inline content; switch to span and update props for better semantics and layout flexibility.

-export interface BadgeProps
-	extends React.HTMLAttributes<HTMLDivElement>,
+export interface BadgeProps
+	extends React.HTMLAttributes<HTMLSpanElement>,
 		VariantProps<typeof badgeVariants> {}
 
-export const Badge = ({ className, variant, ...props }: BadgeProps) => (
-	<div className={cn(badgeVariants({ variant }), className)} {...props} />
-);
+export const Badge = ({ className, variant, ...props }: BadgeProps) => (
+	<span className={cn(badgeVariants({ variant }), className)} {...props} />
+);

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9936b7e and ab27b15.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (9)

• apps/www/components/ui/badge.tsx (1 hunks)
• apps/www/content/docs/guides/import-options.mdx (0 hunks)
• apps/www/content/docs/guides/type-function.mdx (1 hunks)
• apps/www/content/docs/integrations/jetbrains.mdx (1 hunks)
• apps/www/content/docs/integrations/vscode.mdx (1 hunks)
• apps/www/content/docs/meta.json (1 hunks)
• apps/www/lib/source.ts (0 hunks)
• apps/www/lib/source.tsx (1 hunks)
• apps/www/package.json (2 hunks)

💤 Files with no reviewable changes (2)

• apps/www/content/docs/guides/import-options.mdx
• apps/www/lib/source.ts

🧰 Additional context used

🧬 Code graph analysis (2)

apps/www/lib/source.tsx (3)

apps/www/source.config.ts (1)

• docs (6-11)

apps/www/components/ui/badge.tsx (1)

• Badge (29-31)

apps/www/lib/source.ts (2)

• icon (21-30)
• createNewElement (6-16)

apps/www/components/ui/badge.tsx (3)

apps/www/lib/utils/cn.ts (1)

• cn (4-6)

apps/www/components/ui/button.tsx (2)

• ButtonProps (37-41)
• props (44-53)

apps/www/components/ui/toast.tsx (4)

• props (47-55)
• props (76-88)
• props (61-70)
• props (15-24)

🔇 Additional comments (5)

apps/www/content/docs/integrations/vscode.mdx (2)

8-14: Extension link and feature description match Marketplace.

The VS Code extension URL and the “syntax highlighting + inline error summaries” copy align with the Marketplace page. Nice.

Source: ArkType extension on VS Code Marketplace. (marketplace.visualstudio.com)

---

27-31: Verify asset path for the image.

Please ensure /dx.png exists in the public assets and is included in the build output to avoid 404s.

apps/www/content/docs/meta.json (1)

7-9: “New” badge wiring looks compatible with the loader.

Using ---[New]Integrations--- should trigger the “New” sentinel handled by the icon() function in source.tsx. Looks good.

apps/www/package.json (2)

35-37: Deps alignment check (Tailwind v4, TS 5.9).

Dev deps look consistent with Tailwind v4/PostCSS 8 and TS 5.9. No action—just a heads‑up to ensure Next config is on Tailwind v4 presets.

Also applies to: 41-43

---

10-12: Potential script recursion/missing root target — verified safe.

Root package.json defines "fix": "biome check --write .", so the apps/www script "fix": "pnpm -w run fix" will invoke the root script and will not recurse.