Ink Cli

For TypeScript:

npm install --save-dev @types/react

Basic Example

import React from 'react';
import {render, Text} from 'ink';

const App = () => <Text color="green">Hello World</Text>;

render(<App />);

Project Structure

my-cli/
├── source/
│   ├── cli.tsx          # Entry point
│   └── app.tsx          # Main component
├── dist/                # Compiled output
├── package.json
└── tsconfig.json

Key Concepts

1. Components

Ink provides React components that render to terminal output:

• Text: Display styled text
• Box: Layout container with Flexbox support
• Spacer: Fill available space
• Static: Render content only once (for logs)
• Newline: Line breaks

See components.md for detailed documentation.

2. Hooks

Ink extends React with terminal-specific hooks:

• useInput: Handle keyboard input
• useApp: Access app lifecycle (exit, etc.)
• useStdin/useStdout: Raw stdin/stdout access
• useFocus/useFocusManager: Focus management for interactive elements

See hooks.md for detailed documentation.

3. Layout System

Ink uses Flexbox via Yoga:

• All elements are Flexbox containers by default
• Supports flexDirection, justifyContent, alignItems
• Width/height can be numbers (columns/rows) or percentages
• Margins and padding work like CSS

See layouts.md for common patterns.

Development Workflow

1. Entry Point (cli.tsx)

#!/usr/bin/env node
import React from 'react';
import {render} from 'ink';
import App from './app.js';

render(<App />);

2. Main Component (app.tsx)

import React from 'react';
import {Text} from 'ink';

export default function App() {
	return <Text>Hello from Ink!</Text>;
}

3. Build Configuration

TypeScript (tsconfig.json):

{
	"compilerOptions": {
		"module": "Node16",
		"target": "ES2022",
		"lib": ["ES2022"],
		"moduleResolution": "Node16",
		"esModuleInterop": true,
		"strict": true,
		"outDir": "dist",
		"jsx": "react-jsx"
	}
}

package.json:

{
	"type": "module",
	"bin": "dist/cli.js",
	"scripts": {
		"build": "tsc",
		"dev": "tsc --watch",
		"start": "node dist/cli.js"
	}
}

Testing

Ink applications can be tested using ink-testing-library:

npm install --save-dev ink-testing-library

See testing.md for testing patterns and examples.

Common Patterns

• Forms: Input handling with validation
• Menus: Selection interfaces with arrow key navigation
• Wizards: Multi-step flows with state management
• Progress: Loading states and progress bars
• Dashboards: Real-time data layouts

See patterns.md for implementation examples.

Additional Resources

• components.md - Component reference
• hooks.md - Hook documentation
• testing.md - Testing strategies
• layouts.md - Layout patterns
• patterns.md - Common UI patterns
• examples/ - Working code examples

Best Practices

1. Prefer function components - Ink works best with functional components and hooks
2. Use Flexbox for layouts - Leverage Box properties for responsive designs
3. Handle cleanup - Use React's useEffect cleanup for timers and intervals
4. Test interactive components - Use ink-testing-library for reliable tests
5. Consider terminal limitations - Not all terminals support all colors or Unicode
6. Exit gracefully - Always call exit() from useApp() when done

Troubleshooting

Nothing renders: Ensure you're calling render() at the end of your script

Input not working: Make sure you're using useInput hook inside a component rendered by Ink

Layout issues: Remember every element is a Flexbox container by default

TypeScript errors: Ensure you're using "jsx": "react-jsx" in tsconfig.json

External Resources

• Ink GitHub
• Ink Documentation
• create-ink-app - Project scaffolding