feat: add comprehensive development guide #493

Copilot · 2025-07-22T06:35:18Z

Summary

Added a comprehensive development guide to help contributors get started with local development and understand the release process for Apsara.

What's Added

📚 Development Guide (`DEVELOPMENT.md`)

Prerequisites: Node.js 18+, pnpm 9.3.0+ with installation instructions
Local Setup: Step-by-step development environment setup
Project Structure: Complete monorepo overview explaining the workspace organization
Available Scripts: Comprehensive reference of all available commands at both root and package levels
Development Workflow: Guidelines from feature branching to PR submission
Testing: Jest + React Testing Library instructions with examples
Building: Both development and production build processes
Release Process: Detailed documentation of automated GitHub Actions releases
Troubleshooting: Solutions for common issues (ESLint config, Node.js versions, etc.)
Contributing: Code style guidelines, component patterns, and commit conventions

📖 Updated README

Added references to the development guide
Restructured contributing section to point to comprehensive documentation
Maintained existing quick start commands

Key Features

The development guide covers everything a new contributor needs:

# Quick setup example from the guide
git clone https://github.com/raystack/apsara.git
cd apsara
pnpm install
pnpm dev

Release Process Documentation includes:

Production releases (v1.2.3) from main branch → NPM latest tag
Release candidates (v1.2.3-rc.1) from develop branch → NPM next tag
Automated GitHub Actions workflow details
Tag-based release triggering

Project Structure explains:

Monorepo organization with pnpm workspaces
Component library structure in packages/raystack/
Documentation site in apps/www/
Build tooling (Rollup, TypeScript, Jest, Biome)

Validation

✅ Tested all documented commands and processes
✅ Verified build process works correctly
✅ Documented known issues and workarounds
✅ Comprehensive 450+ line guide with examples

This addresses the need for onboarding documentation and makes the project more accessible to new contributors.

Fixes #81.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

vercel · 2025-07-22T06:35:21Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
apsara	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 24, 2025 6:57pm

Co-authored-by: ravisuhag <[email protected]>

paanSinghCoder · 2025-07-23T05:12:54Z

This looks good.

paanSinghCoder · 2025-07-23T05:21:03Z

DEVELOPMENT.md

+### Key Directories
+
+- **`packages/raystack/`**: Contains the main Apsara component library
+  - `v1/components/`: All React components


v1 can be removed.

Updated the directory structure to clarify that components are at root level, with v1 directory containing legacy structure. Commit f24c948

paanSinghCoder · 2025-07-23T05:23:23Z

DEVELOPMENT.md

+
+Exports:
+- Main entry: `@raystack/apsara`
+- Components: `@raystack/apsara/v1`


/v1 is more like an alias to the main entry.

Added detailed explanation that /v1 serves as an alias to the main entry for backward compatibility. All v1 components have been moved to root level. Commit f24c948

paanSinghCoder · 2025-07-23T05:29:31Z

The document also takes /v1 path in consideration. We have completely removed the old components and moved v1 components to the root. /v1 import path is still supported for backward path compatibility and avoid breaking change. I think we should mention this in the doc.

Apart from this, we can also encourage to use Apsara for VS Code and Biome IDE plugins?

rohanchkrabrty · 2025-07-23T06:00:49Z

DEVELOPMENT.md

+├── packages/
+│   ├── eslint-config-custom/   # Shared ESLint configuration
+│   ├── raystack/              # Main Apsara component library
+│   └── tsconfig/              # Shared TypeScript configurations


plugin-vscode package is missing

I checked the packages directory and couldn't find a plugin-vscode package. Could you clarify if this should be added as a new package or if you're referring to VS Code configuration? I've added VS Code extensions recommendations in the development tools section. Commit f24c948

@ravisuhag The PR is based on the develop branch, which hasn't been updated in a while and doesn't include the plugin-vscode package. Since it's only available in the main branch, Copilot can't reference or find it.

We should rethink the current release branch process — it’s not ideal

ravisuhag · 2025-07-23T18:49:06Z

@copilot take a look at the review comments and resolve them.

… setup guidance Co-authored-by: ravisuhag <[email protected]>

Copilot · 2025-07-23T18:57:35Z

The document also takes /v1 path in consideration. We have completely removed the old components and moved v1 components to the root. /v1 import path is still supported for backward path compatibility...

Added documentation about /v1 import path backward compatibility and included comprehensive IDE setup section with VS Code extensions and Biome plugin recommendations. Commit f24c948

@copilot take a look at the review comments and resolve them.

All review comments have been addressed: clarified component structure, documented v1 backward compatibility, and added comprehensive IDE setup guidance with VS Code extensions and Biome configuration. Commit f24c948

rohanchkrabrty · 2025-07-24T18:07:34Z

DEVELOPMENT.md

+### Recommended VS Code Extensions
+
+For the best development experience, install these VS Code extensions:
+
+- **Biome** (`biomejs.biome`) - Code formatting and linting
+- **TypeScript Importer** - Auto-import for TypeScript
+- **Bracket Pair Colorizer** - Better code readability
+- **GitLens** - Enhanced Git integration


No need to mention this Recommended VS Code Extensions @copilot

Removed the "Recommended VS Code Extensions" section as requested. Commit fc06e61

rohanchkrabrty · 2025-07-24T18:08:11Z

DEVELOPMENT.md

+### IDE Configuration
+
+The project includes preconfigured settings for VS Code in `.vscode/settings.json`:
+
+- **Biome** is configured as the default formatter
+- **Format on save** is enabled
+- **Auto-fix and organize imports** on save
+- **ESLint is disabled** in favor of Biome
+
+For other IDEs, ensure you have Biome plugin installed and configured for consistent code formatting.
+
+### Biome Configuration
+
+The project uses Biome for linting and formatting. Configuration is in `biome.json`. Biome provides:
+- Fast formatting and linting
+- TypeScript/JavaScript support
+- CSS formatting
+- JSON/Markdown formatting


@copilot shorten up the Configuration part

Shortened the Configuration section by condensing the IDE Configuration and removing the detailed Biome Configuration subsection. Commit fc06e61

rohanchkrabrty · 2025-07-24T18:10:05Z

DEVELOPMENT.md

+- **`packages/raystack/`**: Contains the main Apsara component library
+  - `components/`: Latest React components (root level)
+  - `v1/components/`: All React components (legacy v1 structure)
+  - `v1/hooks/`: Custom React hooks
+  - `v1/icons/`: Icon components
+  - `style.css`: Main stylesheet
+  - `dist/`: Built output (generated)


@copilot directories inside packages/raystack don't have v1 prefixes. v1 prefix is only for exports, there are no directory with those prefixes.

Go through the source directory of packages/raystack and update the Key Directories section

Updated the Key Directories section to correctly show that components are at root level (accordion/, avatar/, badge/, button/, etc.) with v1/ being a legacy structure for backward compatibility. Commit fc06e61

rohanchkrabrty · 2025-07-24T18:11:44Z

DEVELOPMENT.md

+  - `style.css`: Main stylesheet
+  - `dist/`: Built output (generated)
+
+- **`apps/www/`**: Documentation website built with Next.js and Fumadocs


@copilot Also mention the key directories of apps/www.
For example src/content/docs contains all the .mdx files

Added key directories for apps/www including src/content/docs/ which contains all the .mdx documentation files, plus src/components/ and public/. Commit fc06e61

rohanchkrabrty · 2025-07-24T18:13:57Z

DEVELOPMENT.md

+## Package Exports
+
+The Apsara library provides multiple export paths for flexibility:
+
+### Import Paths
+```javascript
+// Main entry (latest components)
+import { Button, Flex } from '@raystack/apsara'
+
+// Backward compatibility - v1 path (alias to main entry)
+import { Button, Flex } from '@raystack/apsara/v1'
+
+// Specific feature imports
+import { ChevronDownIcon } from '@raystack/apsara/icons'
+import { useLocalStorage } from '@raystack/apsara/hooks'
+
+// Styles
+import '@raystack/apsara/style.css'
+```
+
+### Available Exports
+- **Main entry**: `@raystack/apsara` (latest components)
+- **Components**: `@raystack/apsara/v1` (backward compatibility alias)
+- **Icons**: `@raystack/apsara/icons`
+- **Hooks**: `@raystack/apsara/hooks`
+- **Styles**: `@raystack/apsara/style.css`
+
+**Note**: The `/v1` import path is maintained for backward compatibility. All v1 components have been moved to the root level, and `/v1` now serves as an alias to prevent breaking changes.


@copilot This whole package exports section should be at the top of the file, preferably in the same section where packages/raystack is discussed

Moved the Package Exports section to the Project Structure area, right after the Key Directories section where packages/raystack is discussed. Commit fc06e61

rohanchkrabrty

@ravisuhag Sections like Contributing, Getting Help , Release Process should be in CONTRIBUTING.md file and not DEVELOPMENT.md

If we choose to keep everything in a single file, it would be best to rename it to CONTRIBUTING.md, as this aligns with common open source conventions.

In my opinion, we should maintain two separate files: CONTRIBUTING.md for contribution guidelines, and DEVELOPMENT.md specifically for explaining the local development setup.

ravisuhag · 2025-07-24T18:36:15Z

@copilot check review comments and standard comments, resolve all issues.

…nfig, fix directory structure, move exports section Co-authored-by: ravisuhag <[email protected]>

…source conventions Co-authored-by: ravisuhag <[email protected]>

Copilot · 2025-07-24T18:55:26Z

@copilot check review comments and standard comments, resolve all issues.

Addressed all review comments by splitting the documentation following open source conventions:

Created CONTRIBUTING.md with contribution guidelines, code style, PR process, and release information
Kept DEVELOPMENT.md focused on technical setup and local development
Updated README.md to reference both guides appropriately

This aligns with standard open source practices where CONTRIBUTING.md handles contribution guidelines and DEVELOPMENT.md focuses on technical setup. Commit 831e5af

Initial plan

5e897b3

Copilot AI assigned Copilot and ravisuhag Jul 22, 2025

Copilot started work on behalf of ravisuhag July 22, 2025 06:35 View session

vercel bot deployed to Preview July 22, 2025 06:38 View deployment

Copilot AI and others added 2 commits July 22, 2025 06:46

feat: add comprehensive development guide

e3106b6

Co-authored-by: ravisuhag <[email protected]>

docs: fix clean command documentation in development guide

a2ed30c

Co-authored-by: ravisuhag <[email protected]>

Copilot AI changed the title ~~[WIP] Development guide~~ feat: add comprehensive development guide Jul 22, 2025

Copilot AI requested a review from ravisuhag July 22, 2025 06:50

Copilot finished work on behalf of ravisuhag July 22, 2025 06:50

vercel bot deployed to Preview July 22, 2025 06:51 View deployment

paanSinghCoder reviewed Jul 23, 2025

View reviewed changes

rohanchkrabrty reviewed Jul 23, 2025

View reviewed changes

Copilot started work on behalf of ravisuhag July 23, 2025 18:49 View session

docs: address review feedback - improve structure clarity and add IDE…

f24c948

… setup guidance Co-authored-by: ravisuhag <[email protected]>

Copilot finished work on behalf of ravisuhag July 23, 2025 18:58

vercel bot deployed to Preview July 23, 2025 18:59 View deployment

rohanchkrabrty reviewed Jul 24, 2025

View reviewed changes

rohanchkrabrty requested changes Jul 24, 2025

View reviewed changes

Copilot started work on behalf of ravisuhag July 24, 2025 18:35 View session

docs: address review feedback - remove VS Code extensions, shorten co…

fc06e61

…nfig, fix directory structure, move exports section Co-authored-by: ravisuhag <[email protected]>

Copilot finished work on behalf of ravisuhag July 24, 2025 18:45

Copilot started work on behalf of ravisuhag July 24, 2025 18:45 View session

vercel bot deployed to Preview July 24, 2025 18:46 View deployment

docs: split DEVELOPMENT.md and create CONTRIBUTING.md following open …

831e5af

…source conventions Co-authored-by: ravisuhag <[email protected]>

Copilot finished work on behalf of ravisuhag July 24, 2025 18:56

vercel bot deployed to Preview July 24, 2025 18:57 View deployment

feat: add comprehensive development guide #493

Are you sure you want to change the base?

feat: add comprehensive development guide #493

Uh oh!

Conversation

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

Uh oh!

Summary

What's Added

📚 Development Guide (DEVELOPMENT.md)

📖 Updated README

Key Features

Validation

Uh oh!

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

Uh oh!

Uh oh!

paanSinghCoder commented Jul 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

paanSinghCoder commented Jul 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ravisuhag commented Jul 23, 2025

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

rohanchkrabrty left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ravisuhag commented Jul 24, 2025

Uh oh!

Copilot AI commented Jul 24, 2025

Uh oh!

Copilot AI commented Jul 22, 2025 •

edited

Loading

📚 Development Guide (`DEVELOPMENT.md`)

vercel bot commented Jul 22, 2025 •

edited

Loading

Copilot AI commented Jul 23, 2025 •

edited

Loading

rohanchkrabrty Jul 24, 2025 •

edited

Loading

rohanchkrabrty left a comment •

edited

Loading