@contentstack/venus-components
v3.0.4
Published
Venus components
Readme
Contentstack Venus Component Library
1. Overview
Venus Components is Contentstack's official React component library, providing a comprehensive collection of reusable UI components. It serves as the design system foundation for Contentstack's UI-React application and can be used to build UI Extensions and Contentstack-based applications.
Key Features:
- 100+ production-ready React components
- TypeScript support with full type definitions
- Design token system for consistent theming
- SCSS-based styling with customizable variables
- Comprehensive Storybook documentation
- Accessibility-focused (WCAG AA standards)
- Redux integration for stateful components
- Rich Text Editor components (Slate-based)
- Form components with Formik integration
2. Tech Stack
| Layer | Technology | | ------------------------ | ---------------------------------------------------------------------------------- | | Language | TypeScript 5.3.3 | | Framework | React 18.3.1 | | Build Tool | Rollup 2.23.0 (main bundler) | | Module Bundler | Webpack 4.43.0 (Storybook only) | | Component Library | This is the Venus Components library itself | | State Management | Redux 4.0.5 + React Redux 7.2.1 | | Router | React Router DOM 5.2.0 | | Testing | Jest 27.5.1 + React Testing Library 10.4.9 | | Code Quality | ESLint 8.47.0 + Prettier 2.0.4 | | Component Docs | Storybook 6.5.14 | | Design Tokens | Style Dictionary 2.10.1 | | Styling | SCSS/PostCSS + Design Tokens | | Forms | Formik 2.4.6 | | Rich Text Editor | Slate 0.77.2 | | HTTP Client | Axios 1.8.4 | | Date Handling | date-fns 2.15.0 + Moment.js 2.29.1 |
3. Project Structure
venus-components/
├── .ai/ # AI assistant configurations
│ ├── rules/ # Coding standards and workflows (full docs)
│ ├── skills/ # Domain-specific skill modules (full docs)
│ └── commands/ # Custom Cursor commands (full implementations)
├── .cursor/ # Cursor IDE configurations
│ ├── rules/ # Auto-loaded rule summaries (.mdc files)
│ ├── skills/ # Skill reference (points to .ai/skills/)
│ └── commands/ # Command references (point to .ai/commands/)
├── bin/ # CLI scripts for component creation
├── build/ # Compiled output (generated, do not import from here)
│ ├── components/ # Compiled component files
│ ├── utils/ # Compiled utility files
│ ├── main.css # Bundled CSS styles
│ ├── variables.css/js/scss # Design token variables (built)
│ └── index.js/esm.js # Bundle entry points
├── packages/ # Monorepo packages
│ └── venus-mcp/ # MCP server for AI-assisted development
├── design-tokens/ # Design system token definitions (source)
│ ├── colors/ # Color palette tokens
│ ├── typography/ # Font and text tokens
│ ├── spacing/ # Spacing scale tokens
│ └── ... # Other design token categories
├── tokens/ # Generated token files (import from here)
├── plop-templates/ # Component generation templates
├── scripts/ # Build and utility scripts
├── src/ # Source code
│ ├── components/ # All React components
│ ├── utils/ # Utility functions and helpers
│ ├── static/ # Static assets (fonts, images, styles)
│ ├── index.ts # Main entry point (private build)
│ └── publicIndex.ts # Public API exports (public build)
├── test/ # Test configuration and setup
│ ├── jest.config.js # Jest configuration for components
│ └── jestRte.config.js # Jest configuration for RTE
├── tools/ # Build tools and configurations
│ └── .storybook/ # Storybook configuration
├── design-token-build.js # Design token build script
├── package.json # Dependencies and scripts
├── rollup.config.js # Rollup bundler configuration
└── tsconfig.json # TypeScript configuration4. Getting Started
Prerequisites
- Node.js: v18.0.0+ or v20.x
- npm: v8.19.3+
- Git: Latest version
- React: v16.8.6+ || v17 || v18 || v19 (peer dependency)
Installation for Contributors
$ git clone https://github.com/contentstack/venus-components.git
$ cd venus-components
$ npm install --legacy-peer-deps
$ npm run storybook # Opens at http://localhost:9001
$ npm run build5. Development
Available Scripts
# Development
$ npm run storybook # Start Storybook at http://localhost:9001
$ npm run watch # Watch mode - rebuild on file changes
# Building
$ npm run build # All components for internal apps → /build
$ npm run public-build # Public components only for npm (STORYBOOKMODE=public)
$ npm run build_tokens # Generate design tokens
# Testing (Jest 27.5.1 + React Testing Library 10.4.9)
$ npm test # Run all tests
$ npm run test-jest-config # Run standard component tests
$ npm run test-jest-rte-config # Run Rich Text Editor tests
$ npm run test-watch # Watch mode
$ npm run coverage # Generate coverage report (target: 80%+)
# Requirements: React Testing Library (not Enzyme), test behavior not implementation
# See .ai/rules/unit-testing.md for complete guidelines
# Code Quality
$ npm run lint # Run ESLint
$ npm run commit # Commitizen for conventional commits
# MCP Server (AI Assistant)
$ cd packages/venus-mcp && npm run build # Build MCP server
$ cd packages/venus-mcp && npm run dev # Watch mode
$ cd packages/venus-mcp && npm start # Run MCP server
# Utilities
$ npm run add # Create new component (interactive)
$ npm run clean-install # Clean reinstallCoding Standards
Strict standards enforced through Cursor AI rules: TypeScript types required, React Testing Library mandatory, use SCSS design tokens ($token-name), add data-test-id to interactive elements, wrap async in try-catch.
See .cursor/rules/ and .ai/rules/: coding-standards.md, code-review-guidelines.md, unit-testing.md, snyk_rules.md, dev-workflow.md
6. Using the Library in Your Project
Installation for Consumers
$ npm i @contentstack/venus-components --saveImport and Use
import '@contentstack/venus-components/build/main.css'
import { Button, Table, Modal } from '@contentstack/venus-components'
<Button buttonType="primary" onClick={() => console.log('Clicked!')}>Click Me</Button>Design Tokens
Consumers:
import { TokenName } from '@contentstack/venus-components/build/variables.js'
@import '@contentstack/venus-components/build/variables.css'Developers (internal): Import from tokens/ source, use SCSS variables:
@import '../../tokens/space';
.my-component { padding: $space-4; } // SCSS variables, not var(--space-4)7. Git Workflow
Commit Standards
Use npm run commit for Conventional Commits. Hooks run automatically: pre-commit (lint), pre-push (tests).
Types: feat:, fix:, docs:, refactor:, test:, chore:
8. Cursor AI Features
Rules (.ai/rules/): Mandatory standards - coding standards, testing, code review, security, dev workflow.
Skills (.ai/skills/): Educational modules - Code Review, Debugging, Component Development, Storybook, MCP Server, JsonRTE, RichTextEditor, AssetPicker, Table, Forms.
MCP Server (packages/venus-mcp/): Model Context Protocol server enabling AI-assisted component discovery and code generation. Provides 7 tools for browsing 154+ components, accessing design tokens, generating UI patterns, and searching by functionality. See Venus MCP README and MCP Server Skill for setup and usage.
Commands (.ai/commands/): Custom workflows - /code-review for PR reviews, /debug for structured debugging sessions, /execute-tests for running tests, /update-mcp-server for syncing component changes to MCP, /snyk-fix for security vulnerability fixes.
9. Troubleshooting
Common Issues
Peer dependency conflicts: Use npm install --legacy-peer-deps
Node.js compatibility: Use v18 or v20 (NOT v22). Switch with nvm install 20 && nvm use 20
OpenSSL error: Already fixed via NODE_OPTIONS='--openssl-legacy-provider' in package.json
Module errors: Run npm run clean-install
Test failures: Run npx jest --clearCache && npm test
Token updates: Run npm run build_tokens && npm run build
10. Related Documentation
| Resource | Link | | ------------------------- | ---------------------------------------------------------------------------------- | | Venus Components | GitHub | | UI-React | GitHub - Internal | | React Testing Library | Official Docs | | Storybook | Official Docs | | TypeScript | Official Docs | | Style Dictionary | Official Docs | | Rollup | Official Docs |