A modern, opinionated React starter template designed for rapid UI development, leveraging the power of Vite, TypeScript, Tailwind CSS, and Shadcn UI.
- Overview & Features
- Installation & Setup
- Usage Documentation
- Project Architecture
- Development & Contributing
- Additional Information
This template provides a robust and highly configurable starting point for building modern web applications with React. It integrates a curated set of cutting-edge technologies to enhance developer experience, ensure type safety, and streamline UI development. Designed for performance and maintainability, it offers a seamless workflow from development to production.
The project is pre-configured with a development server, build pipeline, and comprehensive linting rules, allowing you to focus on writing application logic rather than wrestling with configurations. It's an ideal choice for projects prioritizing a clean, modular codebase and a beautiful, accessible user interface.
- ⚡ Blazing Fast Development with Vite 7.x, offering instant server start and hot module replacement (HMR).
- 💪 Type-Safe Code with TypeScript 5.x, ensuring robust and maintainable code.
- 🎨 Utility-First Styling using Tailwind CSS 4.x (Oxide engine), providing highly customizable and efficient styling.
- 🧩 Beautiful & Accessible UI Components powered by Shadcn UI (built on Radix UI and Tailwind CSS), offering a "new-york" style theme with CSS variables.
- 🖼️ Integrated Icon Library with Lucide React, providing a vast collection of customizable icons.
- 🧹 Strict Linting with ESLint 9.x (configured for React, TypeScript, and Hooks) to maintain code quality and consistency.
- 📂 Clear Module Resolution with pre-configured path aliases (
@/) for cleaner and more organized imports. - ✨ Dynamic Animations supported by
tw-animate-cssfor easily adding CSS animations with Tailwind. - 📦 Optimized Production Builds ensuring high performance and small bundle sizes.
Follow these steps to get your development environment up and running.
Before you begin, ensure you have the following installed on your system:
- Node.js: LTS version (e.g., 20.x or higher). You can download it from nodejs.org.
- Bun: Recommended package manager for this project. Install Bun from bun.sh.
-
Clone the repository: You can use
git cloneordegitfor a fresh copy without the git history.Using
degit(recommended for templates):bunx degit asaidimu/uistart my-react-app cd my-react-appOr using
git clone:git clone https://github.com/asaidimu/uistart.git my-react-app cd my-react-app -
Install dependencies: This project uses
bunas its package manager.bun install
-
Verify Installation: Start the development server to ensure everything is set up correctly.
bun run dev
Your application should now be running on
http://localhost:5173(or another port if 5173 is in use).
This section covers the essential commands and common workflows for developing with this template.
To start the local development server with hot module replacement:
bun run devThis will open your application in your browser, typically at http://localhost:5173. Any changes you save will instantly reflect in the browser without a manual refresh.
Note: The vite.config.ts currently sets a base: "/uistart/" for deployment to a sub-path. If you intend to deploy to the root of your domain, remember to change this back to base: "/".
To build the optimized production-ready bundle of your application:
bun run buildThis command first executes tsc -b to compile your TypeScript code, then uses Vite to bundle your assets, and finally outputs them to the dist directory. The build is highly optimized for performance and includes minification, tree-shaking, and code splitting.
To check your codebase for linting errors and enforce coding standards:
bun run lintThis project uses ESLint 9.x with configurations for TypeScript, React, and React Hooks to ensure code quality and consistency across the project.
Shadcn UI components are not installed as traditional NPM packages but are added directly into your project's src/components/ui directory, allowing for easy customization.
To add a new Shadcn UI component (e.g., button):
bunx shadcn-ui@latest add buttonThis command will prompt you to configure the component (e.g., choose where to add it, if you want types, etc.). Ensure your components.json is correctly configured (which it is by default in this template) to use the correct paths and style settings.
Refer to the Shadcn UI documentation for a list of available components and their usage.
This template is configured with a path alias @/ for the src directory, allowing for cleaner and more absolute imports.
Instead of:
import { Button } from '../../components/ui/button';
// or assuming root 'src' from project root
import { Button } from './src/components/ui/button';You can use the alias:
import { Button } from '@/components/ui/button';This alias is configured in tsconfig.json, tsconfig.app.json, and vite.config.ts. Additionally, components.json leverages these aliases for Shadcn UI component generation (e.g., "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui").
This template is structured to promote modularity, scalability, and maintainability.
- Frontend Framework: React 19.1.0 - A powerful library for building user interfaces.
- Build Tool: Vite 7.0.0 - A next-generation frontend tooling that provides an extremely fast development experience.
- Language: TypeScript 5.8.3 - A superset of JavaScript that adds static type definitions.
- Styling: Tailwind CSS 4.1.11 - A utility-first CSS framework for rapidly building custom designs, utilizing the Oxide engine.
- UI Components: Shadcn UI - A collection of re-usable components that you can copy and paste into your apps, built with Radix UI and Tailwind CSS.
- Base Components: Radix UI Primitives - High-quality, accessible UI components for building design systems.
- Icons: Lucide React 0.525.0 - A growing collection of open-source icons.
- Package Manager: Bun - An incredibly fast JavaScript runtime and package manager.
The project follows a logical separation of concerns:
.
├── public/ # Static assets (e.g., vite.svg)
├── src/ # All application source code
│ ├── app/ # Main application entry point (e.g., app.tsx, index.html references src/app/app.tsx)
│ ├── assets/ # Static assets like images, global CSS (app.css as configured in components.json)
│ ├── components/ # Reusable React components
│ │ └── ui/ # Shadcn UI components (copied here via bunx shadcn-ui add)
│ ├── hooks/ # Custom React hooks
│ └── lib/ # Utility functions, helpers (e.g., utils.ts for tailwind-merge/clsx)
├── .eslintrc.js # ESLint configuration for code quality
├── bun.lockb # Bun's lockfile for deterministic dependencies
├── components.json # Shadcn UI configuration file
├── package.json # Project dependencies and scripts
├── tailwind.config.ts # Tailwind CSS configuration
├── tsconfig.app.json # TypeScript configuration for the application
├── tsconfig.json # Root TypeScript configuration, referencing app and node configs
├── tsconfig.node.json # TypeScript configuration for Node.js environment files (e.g., vite.config.ts)
├── vite.config.ts # Vite build configuration
└── ...
- Shadcn UI Customization: Modify component styles directly within
src/components/uias they are part of your codebase, or update yourtailwind.config.tsfor theme changes. Thecomponents.jsonalso allows global style changes likenew-yorktheme orbaseColor. - Tailwind CSS Configuration: Extend Tailwind's default theme, add custom utilities, or configure plugins in
tailwind.config.ts. - Vite Configuration: Adjust build processes, add new Vite plugins, or modify development server settings in
vite.config.ts. Thebaseoption for deployment paths is a common point of adjustment. - ESLint Configuration: Modify or extend linting rules in
.eslintrc.jsto enforce specific coding styles or best practices.
We welcome contributions to this starter template! Follow these guidelines to contribute effectively.
- Ensure you have Node.js and Bun installed (see Prerequisites).
- Clone the repository:
git clone https://github.com/asaidimu/uistart.git cd uistart - Install dependencies using Bun:
bun install
- Start the development server:
bun run dev
These scripts are defined in package.json and are run using bun run <script-name>.
bun run ci: Installs dependencies usingbun install --frozen-lockfile, typically used in CI/CD environments to ensure exact dependency versions.bun run dev: Starts the development server with Vite, enabling hot module replacement for a fast development experience.bun run build: Builds the application for production to thedistfolder. This command also runstsc -bfor TypeScript compilation before building the assets.bun run lint: Runs ESLint to check for code quality and style violations across your codebase.bun run preview: Serves the production build locally for testing purposes, allowing you to verify the optimized output before deployment.
Currently, no dedicated testing framework is pre-configured in this template. For comprehensive testing, consider integrating popular solutions like:
- Vitest: A fast unit test framework powered by Vite, ideal for component and utility testing.
- React Testing Library: For testing React components in a way that resembles how users interact with them, focusing on user behavior rather than implementation details.
- Playwright / Cypress: For robust end-to-end testing of your application's full user flows.
Contributions are what make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: Add some AmazingFeature') - Please follow Conventional Commits for clear and consistent commit messages. - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Please ensure your code adheres to the existing linting rules (bun run lint) and passes any local tests before submitting a pull request.
If you encounter any bugs, have feature requests, or suggestions for improvements, please open an issue on the GitHub Issues page. Provide as much detail as possible, including steps to reproduce, expected behavior, and screenshots where applicable.
- "command not found: bun": Ensure Bun is correctly installed and its executable directory is added to your system's PATH environment variable.
- Dependency Issues: If you face issues with dependencies (e.g., corrupted cache or mismatched versions), try clearing Bun's cache and reinstalling:
bun install --force # Or, if you use npm-check-updates for version upgrades: # bunx npm-check-updates -u && bun install
- Tailwind CSS Not Applying Styles:
- Double-check your
tailwind.config.tsfor correctcontentpaths that cover all your source files. - Ensure
src/assets/app.css(or your main CSS file) includes the@tailwinddirectives (@tailwind base;,@tailwind components;,@tailwind utilities;). - Verify that
tailwind.config.tsis correctly imported and passed to the@tailwindcss/viteplugin invite.config.ts.
- Double-check your
- TypeScript Errors in IDE/Editor: Ensure your IDE or editor (e.g., VS Code) is using the project's locally installed TypeScript version and that all dependencies are installed. Restarting the TypeScript server in your editor often resolves temporary issues.
- How do I update Shadcn UI components?
You can manually update individual components by running
bunx shadcn-ui@latest add <component-name>again. This will prompt you to overwrite existing files, effectively updating them. - Can I change the theme or colors of Shadcn UI components?
Yes, Shadcn UI integrates tightly with Tailwind CSS custom properties. You can modify the base colors and other theme aspects by adjusting values in your
tailwind.config.tsandsrc/assets/app.css(specifically the--<color>-<shade>CSS variables). - Is React Server Components (RSC) supported in this template?
No, this template is configured for client-side rendering. The
components.jsonexplicitly sets"rsc": false, indicating that it's set up for traditional React client applications.
- Changelog: Refer to the CHANGELOG.md for a detailed history of changes (to be created).
- Roadmap:
- Integrate a testing framework (e.g., Vitest + React Testing Library) with example tests.
- Add examples of common UI patterns and components demonstrating best practices.
- Expand comprehensive documentation for each integrated technology within the context of this template.
- Explore adding state management solutions (e.g., Zustand, Jotai) as optional integrations.
This project is licensed under the MIT License. See the LICENSE.md file for full details.
Copyright © 2025 Saidimu