@tamagui/cli 3.0.0-beta.637.1 → 3.0.0-beta.643.1

package/dist/cli.cjs

@@ -223,6 +223,16 @@ const COMMAND_MAP = {
 			});
 		}
 	},
+	setup: {
+		shorthands: [],
+		description: `Print an AI-agent prompt for adding Tamagui to a project for the first time`,
+		usage: `$ tamagui setup`,
+		flags: { "--help": Boolean },
+		async run() {
+			const { printSetupPrompt } = require("./setup-prompt.cjs");
+			printSetupPrompt();
+		}
+	},
 	migrate: {
 		shorthands: [],
 		description: `Print an AI-agent prompt for migrating a Tamagui app to v3`,

package/dist/setup-prompt.cjs

@@ -0,0 +1,158 @@
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: () => from[key],
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var setup_prompt_exports = {};
+__export(setup_prompt_exports, {
+	getSetupPrompt: () => getSetupPrompt,
+	printSetupPrompt: () => printSetupPrompt
+});
+module.exports = __toCommonJS(setup_prompt_exports);
+function printSetupPrompt() {
+	process.stdout.write(getSetupPrompt());
+}
+function getSetupPrompt() {
+	return `You are adding Tamagui v3 to a project that does not use it yet.
+
+Work like a careful coding agent:
+
+- Read the project first: package manager, bundler, framework, TypeScript config,
+  and whether it targets web, native, or both. Every choice below depends on it.
+- Make the smallest install that actually runs, then verify it before adding more.
+- Do not restyle existing components as part of setup.
+- Do not publish packages, rotate secrets, or change production infrastructure.
+- Stop and report if a step cannot be completed rather than guessing around it.
+
+## 1. Check the baseline
+
+Tamagui v3 requires React 19+, TypeScript 5+, and, for native apps, React Native
+0.81+ with the New Architecture enabled. Web-only apps have no React Native
+version requirement. If the project is below any of these, say so and stop.
+
+## 2. Install
+
+Tamagui v3 is currently a beta on the \`beta\` dist-tag. Resolve it once and pin
+every package to the same version, because a mixed install silently produces two
+copies of the runtime and styles that do nothing.
+
+\`\`\`bash
+V=$(npm view tamagui@beta version)
+npm i tamagui@$V @tamagui/config@$V
+\`\`\`
+
+\`tamagui\` is a superset of \`@tamagui/core\`. Install \`@tamagui/core\` alone
+only for a styling-only install with no UI kit.
+
+## 3. Create the config
+
+\`\`\`tsx
+// tamagui.config.ts
+import { defaultConfig } from '@tamagui/config/v6'
+import { createTamagui } from 'tamagui'
+
+export const config = createTamagui(defaultConfig)
+
+declare module 'tamagui' {
+  interface TamaguiCustomConfig extends typeof config {}
+}
+\`\`\`
+
+Pick an animation driver explicitly and import it from \`@tamagui/config\`:
+\`animations-css\` (web), \`animations-rn\`, \`animations-reanimated\`, or
+\`animations-motion\`. Do not install \`@tamagui/theme-builder\` or any v5 builder
+package; they are not part of v3.
+
+## 4. Wrap the app
+
+\`\`\`tsx
+import { TamaguiProvider, View } from 'tamagui'
+import { config } from './tamagui.config'
+
+export default function App() {
+  return (
+    <TamaguiProvider config={config} defaultTheme="light">
+      <View width={200} height={200} bg="background" />
+    </TamaguiProvider>
+  )
+}
+\`\`\`
+
+## 5. Wire the bundler
+
+Add the adapter for the bundler this project actually uses, and no others:
+
+- Vite: \`@tamagui/vite-plugin\`, or \`@tamagui/cli/vite\`
+- Metro: \`@tamagui/metro-plugin\`, or \`@tamagui/cli/metro\`
+- Next.js: \`@tamagui/next-plugin\`
+- Turbopack: the \`tamagui build\` precompile step
+
+There is no Webpack plugin in v3.
+
+The compiler is an optimization, not a requirement. If wiring it is not
+straightforward, skip it, note that you skipped it, and confirm the app runs
+first.
+
+## 6. Write styles the v3 way
+
+This is the part most likely to be written as if it were v2. In v3, token and
+theme names are bare, and conditions are flat clauses inside the value:
+
+\`\`\`tsx
+<View bg="background hover:background-hover" p="4 sm:6" />
+\`\`\`
+
+- No \`$\` sigils: \`bg="background"\`, not \`bg="$background"\`.
+- No condition objects: there is no \`hoverStyle={{ ... }}\` and no \`$sm={{ ... }}\`.
+- Modifiers chain left to right and read as prefixes: \`hover:sm:small\`.
+- Clauses work on variant props too, not just style props, so
+  \`size="large sm:small"\` selects a different variant value per condition.
+- When two clauses both apply, the winner is decided by specificity, not by
+  source order: first by platform (\`ios:\` beats \`native:\` beats unprefixed),
+  then by how many conditions the clause carries, then by category
+  (media < container < theme < group < state). Writing a clause later in the
+  string does not make it win.
+- A chain is capped at five distinct non-platform conditions.
+
+## 7. Verify before reporting success
+
+\`\`\`bash
+npx tamagui check
+\`\`\`
+
+\`tamagui check\` reports version mismatches, duplicate installs, lockfile
+problems, a missing config, and any v2 style syntax left in source. Then run the
+project's own typecheck and build, and start the app and confirm a Tamagui
+component renders with its styles applied. A passing typecheck is not sufficient:
+flat values are strings, so a misspelled token compiles cleanly and only shows up
+at runtime.
+
+## 8. Give the agent the project's own vocabulary
+
+Once the app runs, generate a description of this project's actual tokens,
+themes, and components so later prompts do not guess at them:
+
+\`\`\`bash
+npx tamagui generate-prompt
+\`\`\`
+
+That writes \`tamagui-prompt.md\`. Keep it in the repo and regenerate it when the
+config changes.
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamagui/cli",
-  "version": "3.0.0-beta.637.1",
+  "version": "3.0.0-beta.643.1",
   "bin": {
     "tama": "dist/index.cjs",
     "tamagui": "dist/index.cjs"
@@ -51,12 +51,12 @@
     "test:web": "bun run test"
   },
   "dependencies": {
-    "@tamagui/generate-themes": "3.0.0-beta.637.1",
-    "@tamagui/metro-plugin": "3.0.0-beta.637.1",
-    "@tamagui/static": "3.0.0-beta.637.1",
-    "@tamagui/to-tailwind": "3.0.0-beta.637.1",
-    "@tamagui/types": "3.0.0-beta.637.1",
-    "@tamagui/vite-plugin": "3.0.0-beta.637.1",
+    "@tamagui/generate-themes": "3.0.0-beta.643.1",
+    "@tamagui/metro-plugin": "3.0.0-beta.643.1",
+    "@tamagui/static": "3.0.0-beta.643.1",
+    "@tamagui/to-tailwind": "3.0.0-beta.643.1",
+    "@tamagui/types": "3.0.0-beta.643.1",
+    "@tamagui/vite-plugin": "3.0.0-beta.643.1",
     "arg": "^5.0.2",
     "chalk": "^4.1.2",
     "change-case": "^4.1.2",
@@ -75,10 +75,10 @@
     "ts-morph": "^28.0.0",
     "typescript": "~6.0.3",
     "url": "^0.11.0",
-    "@tamagui/language-service": "3.0.0-beta.637.1"
+    "@tamagui/language-service": "3.0.0-beta.643.1"
   },
   "devDependencies": {
-    "@tamagui/build": "3.0.0-beta.637.1",
+    "@tamagui/build": "3.0.0-beta.643.1",
     "@types/chokidar": "^2.1.3",
     "@types/marked": "^5.0.0",
     "vitest": "4.0.4"

package/src/cli.ts

@@ -242,6 +242,19 @@ const COMMAND_MAP = {
     },
   },
 
+  setup: {
+    shorthands: [],
+    description: `Print an AI-agent prompt for adding Tamagui to a project for the first time`,
+    usage: `$ tamagui setup`,
+    flags: {
+      '--help': Boolean,
+    },
+    async run() {
+      const { printSetupPrompt } = require('./setup-prompt')
+      printSetupPrompt()
+    },
+  },
+
   migrate: {
     shorthands: [],
     description: `Print an AI-agent prompt for migrating a Tamagui app to v3`,

package/src/setup-prompt.ts

@@ -0,0 +1,139 @@
+// The agent brief for setting Tamagui up in a project that has never had it.
+// `tamagui migrate --from v2` is the sibling for projects that already run v2.
+//
+// Both are printed by the CLI rather than kept only in docs so that whatever
+// version a user installs describes itself, instead of an agent reading a docs
+// page written against a different release.
+
+export function printSetupPrompt() {
+  process.stdout.write(getSetupPrompt())
+}
+
+export function getSetupPrompt() {
+  return `You are adding Tamagui v3 to a project that does not use it yet.
+
+Work like a careful coding agent:
+
+- Read the project first: package manager, bundler, framework, TypeScript config,
+  and whether it targets web, native, or both. Every choice below depends on it.
+- Make the smallest install that actually runs, then verify it before adding more.
+- Do not restyle existing components as part of setup.
+- Do not publish packages, rotate secrets, or change production infrastructure.
+- Stop and report if a step cannot be completed rather than guessing around it.
+
+## 1. Check the baseline
+
+Tamagui v3 requires React 19+, TypeScript 5+, and, for native apps, React Native
+0.81+ with the New Architecture enabled. Web-only apps have no React Native
+version requirement. If the project is below any of these, say so and stop.
+
+## 2. Install
+
+Tamagui v3 is currently a beta on the \`beta\` dist-tag. Resolve it once and pin
+every package to the same version, because a mixed install silently produces two
+copies of the runtime and styles that do nothing.
+
+\`\`\`bash
+V=$(npm view tamagui@beta version)
+npm i tamagui@$V @tamagui/config@$V
+\`\`\`
+
+\`tamagui\` is a superset of \`@tamagui/core\`. Install \`@tamagui/core\` alone
+only for a styling-only install with no UI kit.
+
+## 3. Create the config
+
+\`\`\`tsx
+// tamagui.config.ts
+import { defaultConfig } from '@tamagui/config/v6'
+import { createTamagui } from 'tamagui'
+
+export const config = createTamagui(defaultConfig)
+
+declare module 'tamagui' {
+  interface TamaguiCustomConfig extends typeof config {}
+}
+\`\`\`
+
+Pick an animation driver explicitly and import it from \`@tamagui/config\`:
+\`animations-css\` (web), \`animations-rn\`, \`animations-reanimated\`, or
+\`animations-motion\`. Do not install \`@tamagui/theme-builder\` or any v5 builder
+package; they are not part of v3.
+
+## 4. Wrap the app
+
+\`\`\`tsx
+import { TamaguiProvider, View } from 'tamagui'
+import { config } from './tamagui.config'
+
+export default function App() {
+  return (
+    <TamaguiProvider config={config} defaultTheme="light">
+      <View width={200} height={200} bg="background" />
+    </TamaguiProvider>
+  )
+}
+\`\`\`
+
+## 5. Wire the bundler
+
+Add the adapter for the bundler this project actually uses, and no others:
+
+- Vite: \`@tamagui/vite-plugin\`, or \`@tamagui/cli/vite\`
+- Metro: \`@tamagui/metro-plugin\`, or \`@tamagui/cli/metro\`
+- Next.js: \`@tamagui/next-plugin\`
+- Turbopack: the \`tamagui build\` precompile step
+
+There is no Webpack plugin in v3.
+
+The compiler is an optimization, not a requirement. If wiring it is not
+straightforward, skip it, note that you skipped it, and confirm the app runs
+first.
+
+## 6. Write styles the v3 way
+
+This is the part most likely to be written as if it were v2. In v3, token and
+theme names are bare, and conditions are flat clauses inside the value:
+
+\`\`\`tsx
+<View bg="background hover:background-hover" p="4 sm:6" />
+\`\`\`
+
+- No \`$\` sigils: \`bg="background"\`, not \`bg="$background"\`.
+- No condition objects: there is no \`hoverStyle={{ ... }}\` and no \`$sm={{ ... }}\`.
+- Modifiers chain left to right and read as prefixes: \`hover:sm:small\`.
+- Clauses work on variant props too, not just style props, so
+  \`size="large sm:small"\` selects a different variant value per condition.
+- When two clauses both apply, the winner is decided by specificity, not by
+  source order: first by platform (\`ios:\` beats \`native:\` beats unprefixed),
+  then by how many conditions the clause carries, then by category
+  (media < container < theme < group < state). Writing a clause later in the
+  string does not make it win.
+- A chain is capped at five distinct non-platform conditions.
+
+## 7. Verify before reporting success
+
+\`\`\`bash
+npx tamagui check
+\`\`\`
+
+\`tamagui check\` reports version mismatches, duplicate installs, lockfile
+problems, a missing config, and any v2 style syntax left in source. Then run the
+project's own typecheck and build, and start the app and confirm a Tamagui
+component renders with its styles applied. A passing typecheck is not sufficient:
+flat values are strings, so a misspelled token compiles cleanly and only shows up
+at runtime.
+
+## 8. Give the agent the project's own vocabulary
+
+Once the app runs, generate a description of this project's actual tokens,
+themes, and components so later prompts do not guess at them:
+
+\`\`\`bash
+npx tamagui generate-prompt
+\`\`\`
+
+That writes \`tamagui-prompt.md\`. Keep it in the repo and regenerate it when the
+config changes.
+`
+}

package/types/setup-prompt.d.ts

@@ -0,0 +1,3 @@
+export declare function printSetupPrompt(): void;
+export declare function getSetupPrompt(): string;
+//# sourceMappingURL=setup-prompt.d.ts.map

package/types/setup-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-prompt.d.ts","sourceRoot":"","sources":["../src/setup-prompt.ts"],"names":[],"mappings":"AAOA,wBAAgB,gBAAgB,SAE/B;AAED,wBAAgB,cAAc,WA+H7B"}