Local Development Environment
Relevant source files
The following files were used as context for generating this wiki page:The CyberPath project can be installed and run locally for development and contribution purposes. While the official website is recommended for general use, a local setup provides an environment to test changes, add features, or explore the codebase. The project is built with Astro, React, and Tailwind CSS.
This document outlines the necessary steps for installation, configuration, and running the application on a local machine. It also covers the key scripts and tools used in the development workflow.
Sources: README.md:1-4, 21-28
Installation and Setup
To run the CyberPath platform locally, you must first clone the repository and install the required dependencies using pnpm.
Sources: README.md:29-41
Prerequisites
The only explicit dependency manager mentioned for installation is pnpm.
Sources: README.md:39
Setup Steps
The following diagram illustrates the sequence of commands to get the local development environment running.
Sources: README.md:33-49, package.json:5
- Clone the repository:
git clone https://github.com/ebalo55/cyberpath.git - Navigate into the directory:
cd cyberpath - Install dependencies:
pnpm install - Run the development server:
pnpm run dev - Access the application: Open your browser and go to
http://localhost:4321.
Sources: README.md:33-49
Project Configuration
The project utilizes several configuration files to manage its structure, dependencies, and build process.
Core Technologies and Dependencies
The project is built on a modern web stack. Key dependencies are defined in package.json.
- Framework: Astro
- UI Components: React
- Styling: Tailwind CSS
- Type Checking: TypeScript
Other notable dependencies include Headless UI, Framer Motion, Fuse.js for searching, and Sentry for error monitoring.
Sources: package.json:11-27, astro.config.ts:2-11
Astro Configuration
The main configuration for the Astro framework is located in astro.config.ts. It defines the site URL and integrates various tools.
| Integration | Purpose |
|---|---|
tailwind | Integrates Tailwind CSS with nesting support. |
sentry | Enables Sentry error tracking in development. |
spotlightjs | Adds Spotlight.js for debugging. |
react | Enables the use of React components. |
sitemap | Generates a sitemap for the site. |
mdx | Allows using MDX files with GFM support. |
The build output directory is configured to be dist/assets.
Sources: astro.config.ts:14-28
TypeScript Configuration
The tsconfig.json file extends Astro's strict configuration and sets up path aliases for easier module imports within the project.
"paths": {
"@components/*": [
"src/components/*"
],
"@layouts/*": [
"src/layouts/*"
],
"@assets/*": [
"src/assets/*"
]
}
This configuration allows for cleaner import statements, like import Component from '@components/react/button.tsx'.
Sources: tsconfig.json:5-15
Tailwind CSS Configuration
The tailwind.config.ts file configures the styling framework. It sets the dark mode to be class-based, extends the default theme with a custom Nunito Variable font, and adds a custom bounce-horizontal animation. It also includes plugins for forms, typography, and aspect-ratio.
Sources: tailwind.config.ts:8-33
NPM Scripts
The package.json file defines several scripts for common development tasks.
| Script | Description |
|---|---|
dev | Starts the Astro development server. |
start | An alias for the dev script. |
build | Runs astro check for type checking, then astro build to create a production build. It also installs Chrome via Puppeteer and runs the scripts/screenshot.js script. |
preview | Starts a local server to preview the production build. |
astro | Provides direct access to the Astro CLI. |
Sources: package.json:4-10
Build Process
The production build is initiated by the pnpm run build command. This triggers a multi-step process.
The following diagram shows the flow of the build script:
Sources: package.json:7
Screenshot Script
A key part of the build process is the scripts/screenshot.js script. This Node.js script uses Puppeteer to automate taking a screenshot of the application's database page.
The script performs the following actions:
- Spawns the Astro development server (
npm run dev). - Waits 10 seconds for the server to start.
- Launches a headless Puppeteer browser.
- Navigates to
http://localhost:4321/database/. - Removes the cookie banner and scrolls down to hide the header.
- Waits another 10 seconds for React to render the data.
- Takes a screenshot of the page.
- Uses the
sharplibrary to crop and optimize the screenshot into a WebP image. - Saves the image to the
./dist/assetsdirectory. - Kills the development server process.
Sources: scripts/screenshot.js
Contribution Workflow
For developers looking to contribute, the project follows a standard GitHub fork-and-pull-request workflow.
This diagram outlines the contribution process from forking the repository to submitting a pull request for review.
Sources: CONTRIBUTING.md:6-26