feat(sdk): add create-nitrolite-app project scaffolding tool #286

maxpushka · 2025-07-18T07:07:40Z

No description provided.

gemini-code-assist

Summary of Changes

Hello @maxpushka, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a new create-nitrolite-app CLI tool, enabling developers to quickly scaffold Nitrolite applications with a guided interactive experience. It includes a fully-featured Next.js template that integrates essential SDK components and modern web development practices, significantly accelerating project setup for Nitrolite-based applications.

Highlights

New Project Scaffolding CLI: This PR introduces create-nitrolite-app, a new interactive command-line interface (CLI) tool built with Ink and React, designed to streamline the creation of new Nitrolite applications.
Next.js Application Template: A comprehensive nextjs-app template has been added, featuring Next.js 15 with App Router, TypeScript, TailwindCSS, and pre-configured integration with the Nitrolite SDK, Privy.io for authentication, Viem for blockchain interactions, and Valtio for state management.
Interactive Setup and Generation: The CLI guides users through project setup, including directory naming, Git initialization, and template selection, with real-time progress updates during file copying, templating, and dependency installation. It also supports non-interactive mode via CLI flags.
WebSocket Integration Utilities: The Next.js template includes a robust set of components, hooks, and state management stores (YellowWebSocketProvider, useYellowWebSocket, AssetsStore, etc.) for handling WebSocket connections, authentication, and data synchronization with a 'Yellow' service.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a new project scaffolding tool, create-nitrolite-app. There are several inconsistencies regarding the available templates. The default template is often referred to as react-vite, but this template is not included, and the UI for template selection shows different options. This should be unified. I've also identified a critical issue in the Next.js template regarding environment variable handling, and a few other areas for improvement in terms of code quality and correctness. Please see my detailed comments.

gemini-code-assist · 2025-07-18T07:10:23Z

sdk/create-nitrolite-app/templates/nextjs-app/src/utils/env.ts

+export const isDevelopment = import.meta.env.DEV;
+export const isProduction = import.meta.env.PROD;
+
+export const config = {
+  isDev: isDevelopment,
+  isProd: isProduction,
+  yellowWsUrl: import.meta.env.VITE_YELLOW_WS_URL || 'wss://clearnet.yellow.com/ws',
+  asset: import.meta.env.VITE_ASSET || 'usdc',
+  vApp: {
+    name: import.meta.env.VITE_VAPP_NAME || '',
+    scope: import.meta.env.VITE_VAPP_SCOPE || '',
+  },
+} as const;


This file uses import.meta.env and VITE_* prefixed environment variables, which will not work in a Next.js application. Next.js exposes environment variables through process.env and they must be prefixed with NEXT_PUBLIC_.

Suggested change

export const isDevelopment = import.meta.env.DEV;

export const isProduction = import.meta.env.PROD;

export const config = {

isDev: isDevelopment,

isProd: isProduction,

yellowWsUrl: import.meta.env.VITE_YELLOW_WS_URL || 'wss://clearnet.yellow.com/ws',

asset: import.meta.env.VITE_ASSET || 'usdc',

vApp: {

name: import.meta.env.VITE_VAPP_NAME || '',

scope: import.meta.env.VITE_VAPP_SCOPE || '',

},

} as const;

export const isDevelopment = process.env.NODE_ENV === 'development';

export const isProduction = process.env.NODE_ENV === 'production';

export const config = {

isDev: isDevelopment,

isProd: isProduction,

yellowWsUrl: process.env.NEXT_PUBLIC_YELLOW_WS_URL || 'wss://clearnet.yellow.com/ws',

asset: process.env.NEXT_PUBLIC_ASSET || 'usdc',

vApp: {

name: process.env.NEXT_PUBLIC_VAPP_NAME || '',

scope: process.env.NEXT_PUBLIC_VAPP_SCOPE || '',

},

} as const;

gemini-code-assist · 2025-07-18T07:10:23Z

sdk/create-nitrolite-app/templates/nextjs-app/src/utils/crypto.ts

+  const privateKey = generatePrivateKey();
+  const privateKeyHash = keccak256(toBytes(privateKey));
+  const account = privateKeyToAccount(privateKeyHash);


The private key is generated and then immediately hashed with keccak256. This is a non-standard way of handling private keys. Use the raw private key to derive the public key and address. If this is intentional, document the rationale.

Suggested change

const privateKey = generatePrivateKey();

const privateKeyHash = keccak256(toBytes(privateKey));

const account = privateKeyToAccount(privateKeyHash);

const account = privateKeyToAccount(privateKey);

gemini-code-assist · 2025-07-18T07:10:23Z

sdk/create-nitrolite-app/tsconfig.json

+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": false,


The TypeScript compiler option strict is set to false. Enabling strict mode ("strict": true) is highly recommended for stronger guarantees of program correctness.

"strict": true,

gemini-code-assist · 2025-07-18T07:10:24Z

sdk/create-nitrolite-app/README.md

+
+| Option              | Description                  | Default      |
+| ------------------- | ---------------------------- | ------------ |
+| `--template <name>` | Template to use              | `react-vite` |


The default template in the CLI options table is react-vite, but this template isn't described in the "Available Templates" section and is not included in the pull request. This inconsistency could confuse users.

gemini-code-assist · 2025-07-18T07:10:24Z

sdk/create-nitrolite-app/README.md

+```
+my-nitrolite-app/
+├── src/
+│   ├── components/        # React/Vue components
+│   ├── hooks/             # Custom hooks (React)
+│   ├── composables/       # Composables (Vue)
+│   ├── utils/             # Utility functions
+│   └── main.tsx           # Entry point
+├── public/                # Static assets
+├── package.json
+└── README.md
+```


The project structure example seems to be for a Vite-based project (e.g., src/main.tsx, src/hooks/). This doesn't match the nextjs-app template, which uses an app/ directory. This could be misleading.

gemini-code-assist · 2025-07-18T07:10:24Z

sdk/create-nitrolite-app/src/components/TemplateSelector.tsx

+const TEMPLATES: Template[] = [
+  {
+    id: 'nextjs-app',
+    name: 'Next.js App Router',
+    description: 'Next.js with App Router, TypeScript, and TailwindCSS',
+    features: ['Next.js 15', 'App Router', 'TypeScript', 'TailwindCSS', 'SSR support'],
+  },
+  {
+    id: 'minimal-sdk',
+    name: 'Minimal SDK Integration',
+    description: 'Minimal setup with just the Nitrolite SDK',
+    features: ['TypeScript', 'Minimal setup', 'WebSocket client', 'SDK only'],
+  },
+];


The list of available templates is hardcoded. To improve maintainability, consider dynamically reading the available templates from the filesystem instead.

gemini-code-assist · 2025-07-18T07:10:24Z

sdk/create-nitrolite-app/src/index.tsx

+  .description('CLI tool to create new Nitrolite applications')
+  .version('1.0.0')
+  .argument('[project-directory]', 'directory where the project will be created')
+  .option('-t, --template <template>', 'template to use', 'react-vite')


The default template is hardcoded to react-vite, which is not an available template in this PR. Update this to a valid, available template like nextjs-app.

.option('-t, --template <template>', 'template to use', 'nextjs-app')

gemini-code-assist · 2025-07-18T07:10:24Z

sdk/create-nitrolite-app/src/utils/projectGenerator.ts

@@ -0,0 +1,295 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';


execSync blocks the Node.js event loop. Use execa for a more robust, async-friendly API for executing child processes.

Suggested change

import { execSync } from 'child_process';

import { execa } from 'execa';

gemini-code-assist · 2025-07-18T07:10:24Z

sdk/create-nitrolite-app/src/utils/validation.ts

+export async function checkGitAvailability(): Promise<boolean> {
+  try {
+    execSync('git --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }


checkGitAvailability is declared as async but uses the synchronous execSync. Use an asynchronous execution method like execa to match the function signature.

Suggested change

export async function checkGitAvailability(): Promise<boolean> {

try {

execSync('git --version', { stdio: 'ignore' });

return true;

} catch {

return false;

}

export async function checkGitAvailability(): Promise<boolean> {

try {

await execa('git', ['--version'], { stdio: 'ignore' });

return true;

} catch {

return false;

}

}

gemini-code-assist · 2025-07-18T07:10:25Z

sdk/create-nitrolite-app/templates/nextjs-app/src/components/yellow/YellowWebSocketProvider.tsx

+const YellowWebSocketContext = createContext<YellowWebSocketContextType | null>(null);
+
+interface YellowWebSocketProviderProps {
+    children: typeof Children;


The type for the children prop is typeof Children, which is incorrect. The correct type is React.ReactNode.

children: React.ReactNode;

maxpushka added 12 commits July 17, 2025 17:38

feat: scaffold nextjs project

4237b7a

feat: add CLI tool

b38fe76

fix: make welcome screen responsive

2bcd721

feat: add ascii art

bca4ad6

refactor: make welcome screen persistent

7cc278e

feat: exit the process after showing the completion message

0101a01

refactor: drop unused imports

fb0d1f2

feat: drop redundant templates

e7ab55e

refactor: rename nextjs template

4ccafed

feat: add NextJS template

dae8ae7

refactor: update connection status text

c27b533

docs: add README.md for scaffolding tool

46c422f

maxpushka added the Ready for Review label Jul 18, 2025

maxpushka requested a review from akushniruk July 18, 2025 07:07

gemini-code-assist bot reviewed Jul 18, 2025

View reviewed changes

maxpushka added 3 commits July 18, 2025 12:30

feat: move template selectin before confirmation

725233f

fix: privy auth

7ce8255

feat: add backend template

7196b62

maxpushka added wip and removed Ready for Review labels Jul 21, 2025

maxpushka added 9 commits July 21, 2025 13:50

fix: pass template directly to project generator

a19b794

refactor: extract utility functions

6ee64ca

refactor: rework nitrolite client

bf89f43

refactor: modularize client for maintainability

c850b70

refactor: logging cleanup

644da31

refactor: remove redundant logs

eb3b675

fix: deduplicate auth_challenge processing

cd1989f

refactor: drop dependency on express

cbbec6e

refactor: drop dependency on ethers

cc7ad6b

maxpushka added Ready for Review and removed wip labels Jul 22, 2025

nksazonov added the single-component label Jul 27, 2025

	import { execSync } from 'child_process';
	import { execa } from 'execa';

feat(sdk): add create-nitrolite-app project scaffolding tool #286

Are you sure you want to change the base?

feat(sdk): add create-nitrolite-app project scaffolding tool #286

Uh oh!

Conversation

maxpushka commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maxpushka commented Jul 18, 2025 •

edited

Loading