Skip to content
Accessible Astro Documentation

Development

Development setup

Before you start contributing, make sure you have the right tools and environment set up. This guide will help you get up and running with the project quickly.

Prerequisites

  • Node.js 18.14.1 or higher
  • npm, pnpm, or Yarn
  • Git

Local development

Getting the development environment running is straightforward. Follow these steps to start contributing:

  1. Install dependencies:
Terminal window
npm install
  1. Start development server:
Terminal window
npm run dev
  1. Run tests:
Terminal window
npm run test

Project structure

Understanding the project structure helps you navigate the codebase more effectively. Here’s an overview of our main directories:

Terminal window
accessible-astro-components/
├── src/
│   ├── components/     # Component source files
│   ├── styles/        # Global styles and variables
│   └── utils/         # Utility functions
├── tests/             # Test files
└── package.json       # Project configuration

Coding standards

We maintain high coding standards to ensure our components are accessible, performant, and maintainable. Here are our key guidelines:

TypeScript

  • Use TypeScript for all new code
  • Include proper type definitions
  • Avoid any types where possible

Components

  • Follow the WAI-ARIA guidelines
  • Include proper ARIA attributes
  • Support keyboard navigation
  • Test with screen readers

CSS

  • Use logical properties
  • Follow mobile-first approach
  • Support dark mode
  • Respect user preferences

Testing

Quality assurance is crucial for our components. We use different types of tests to ensure everything works as expected:

Unit tests

Terminal window
npm run test:unit

Integration tests

Terminal window
npm run test:integration

Accessibility tests

Terminal window
npm run test:a11y

Building

When you’re ready to create a production build:

Terminal window
npm run build

Common tasks

Here are some frequent development tasks and how to handle them:

Adding a new component

  1. Create component file:
Terminal window
src/components/NewComponent.tsx
  1. Add tests:
Terminal window
tests/NewComponent.test.ts
  1. Update documentation:
Terminal window
docs/components/new-component.mdx

Updating dependencies

Regular dependency updates help keep the project secure and up-to-date:

  1. Check for updates:
Terminal window
npm outdated
  1. Update packages:
Terminal window
npm update
  1. Test thoroughly after updates

Troubleshooting

When you run into issues, here are some common solutions:

Common issues

  1. Build errors

    • Clear the cache: npm run clean
    • Remove node_modules: rm -rf node_modules
    • Fresh install: npm install

  2. Test failures

    • Check test coverage: npm run test:coverage
    • Run specific tests: npm run test NewComponent.test.ts

Performance

Performance is a key aspect of accessibility. Keep these principles in mind:

  • Use lazy loading where appropriate
  • Optimize images and assets
  • Keep bundle size minimal
  • Monitor performance metrics

Resources

Here are some helpful resources to learn more: