create-nudge-ui 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +78 -40
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,67 +1,105 @@
1
- # `create-nudge-ui`
1
+ # create-nudge-ui
2
2
 
3
- `create-nudge-ui` detects an application's host framework, installs the
4
- corresponding Nudge UI adapter, and updates the host configuration. The guided
5
- setup can also connect a coding agent to Nudge.
3
+ Add Nudge UI to an existing app with one command. `create-nudge-ui` detects your
4
+ framework, installs `nudge-ui`, and updates your development configuration. It
5
+ can also connect your coding agent so you can send design changes from the browser.
6
6
 
7
- Run the initializer from the application root:
7
+ [Nudge UI](https://www.npmjs.com/package/nudge-ui) lets you inspect your running
8
+ app, preview visual edits, and turn them into a prompt for a coding agent.
9
+
10
+ ## Get started
11
+
12
+ From your application's root directory, run:
8
13
 
9
14
  ```sh
10
15
  npm create nudge-ui@latest
11
16
  ```
12
17
 
13
- The initializer supports Next.js, Astro, Vite with React, and static HTML. Host
14
- frameworks take precedence over their underlying tools, so an Astro project
15
- with React islands receives `nudge-ui/astro`, not `nudge-ui/vite`.
18
+ Follow the prompts, then start your app with its usual development command and
19
+ open the local URL. For static HTML, run the `nudge-ui serve` command printed by
20
+ the initializer.
21
+
22
+ Requires Node.js 20 or later and a supported app. Your framework or build tool
23
+ may require a newer Node.js version.
16
24
 
17
- In an interactive terminal, the initializer asks whether to connect a coding
18
- agent. It detects installed agents, installs the matching `@nudge-ui/mcp`
19
- version in the project, and installs a versioned reusable adapter under
20
- `~/.nudge-ui/adapters/`. The adapter is independent of the application and
21
- does not contain a project path, so different Git worktrees can use the same
22
- global MCP registration. Existing project-scoped Nudge entries are backed up
23
- and removed when the host supports that migration.
25
+ ## What setup does
24
26
 
25
- Fully restart the agent host, then ask it to “listen to Nudge.”
27
+ - Detects Next.js, Astro, Vite with React, or a static HTML directory.
28
+ - Installs `nudge-ui` as a development dependency using npm, pnpm, Yarn, or Bun.
29
+ - Adds the framework integration to your configuration. Static HTML uses the
30
+ bundled development server instead.
31
+ - Offers to connect a coding agent through
32
+ [`@nudge-ui/mcp`](https://www.npmjs.com/package/@nudge-ui/mcp).
26
33
 
27
- Use an explicit framework when automatic detection is ambiguous:
34
+ Run it inside the app directory in a monorepo. If detection is ambiguous, choose
35
+ the framework explicitly:
28
36
 
29
37
  ```sh
30
38
  npm create nudge-ui@latest -- --framework astro
31
39
  ```
32
40
 
33
- Use `--dry-run` to print the package installation and configuration change
34
- without modifying the project. Run `npm create nudge-ui@latest -- --help` for
35
- the complete command reference.
41
+ ## Connect a coding agent
36
42
 
37
- For scripts, select the MCP behavior explicitly:
43
+ Choose agent setup during initialization, or add it later:
38
44
 
39
45
  ```sh
40
- # Configure detected agents without prompts.
41
- npm create nudge-ui@latest -- --mcp --yes
46
+ npm create nudge-ui@latest -- --agent-only
47
+ ```
42
48
 
43
- # Configure one or more supported add-mcp agent IDs.
44
- npm create nudge-ui@latest -- --mcp --agent codex --agent cursor --yes
49
+ Setup installs a bridge dependency in the app and a reusable MCP adapter under
50
+ `~/.nudge-ui/adapters/`. It registers the adapter globally for the selected
51
+ agents, so other checkouts and Git worktrees can use it. Each app still needs
52
+ its own Nudge integration and bridge dependency.
45
53
 
46
- # Skip agent setup.
47
- npm create nudge-ui@latest -- --no-mcp
48
- ```
54
+ Setup verifies the adapter before changing agent settings. If automatic
55
+ configuration fails, it prints a global stdio configuration you
56
+ can add manually. npm must be available to install the reusable adapter, even
57
+ when your app uses another package manager.
49
58
 
50
- Use agent-only mode to add or repair the integration without changing the host
51
- framework configuration:
59
+ Fully restart your agent host, then ask it to **listen to Nudge in this
60
+ workspace**. Keep the agent listening while you send changes from the browser.
61
+ The MCP integration is early alpha; host behavior and setup may change.
62
+
63
+ ## Common commands
52
64
 
53
65
  ```sh
54
- npm create nudge-ui@latest -- --agent-only --agent codex --yes
55
- ```
66
+ # Preview setup without changing files or installing packages.
67
+ npm create nudge-ui@latest -- --dry-run
56
68
 
57
- For local MCP package testing, pass a tarball with `--mcp-package`. Setup uses
58
- that artifact for both the project bridge and reusable adapter:
69
+ # Install the inspector without agent setup.
70
+ npm create nudge-ui@latest -- --no-mcp
59
71
 
60
- ```sh
61
- npx nudge-ui agent setup --mcp-package /absolute/path/to/nudge-ui-mcp.tgz
72
+ # Set up a specific agent without prompts.
73
+ npm create nudge-ui@latest -- --agent codex --yes
74
+
75
+ # Connect an agent to an existing Nudge installation.
76
+ npm create nudge-ui@latest -- --agent-only --agent cursor --yes
62
77
  ```
63
78
 
64
- Agent configuration is best-effort. If an agent is not supported or its native
65
- configuration cannot be updated, the initializer prints the complete stdio
66
- configuration to add to that agent's project settings. Other MCP servers and
67
- agent settings are preserved on every run.
79
+ ## Options
80
+
81
+ Pass options after `--` when using `npm create`.
82
+
83
+ | Option | Purpose |
84
+ | --- | --- |
85
+ | `--framework <name>` | Select `nextjs`, `astro`, `vite-react`, or `standalone`. |
86
+ | `--package-manager <name>` | Select `npm`, `pnpm`, `yarn`, or `bun`. |
87
+ | `--mcp` | Enable agent setup. |
88
+ | `--no-mcp` | Skip agent setup. |
89
+ | `--agent <id>` | Select an agent, such as `codex` or `cursor`. Repeat for multiple agents. Enables agent setup. |
90
+ | `--agent-only` | Install or repair agent integration without changing framework configuration. |
91
+ | `--yes`, `-y` | Accept defaults without prompts, including setup for detected agents. Use `--no-mcp` to skip agent setup. |
92
+ | `--dry-run` | Print planned changes without applying them. |
93
+ | `--mcp-package <specifier>` | Use a specific MCP package or local tarball for both the bridge and adapter. |
94
+ | `--help`, `-h` | Show command help. |
95
+
96
+ For troubleshooting and custom integrations, see the
97
+ [coding-agent guide](https://github.com/charlessmart/nudge-ui/blob/main/docs/agent-integration.md).
98
+ For manual framework setup, see
99
+ [`nudge-ui`](https://www.npmjs.com/package/nudge-ui).
100
+
101
+ ## Links
102
+
103
+ [Repository](https://github.com/charlessmart/nudge-ui) ·
104
+ [Issues](https://github.com/charlessmart/nudge-ui/issues) ·
105
+ [MIT license](https://github.com/charlessmart/nudge-ui/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-nudge-ui",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "Framework-detecting installer for Nudge UI.",
5
5
  "license": "MIT",
6
6
  "repository": {