Skip to main content

​
Development Setup

This guide is for developers and contributors who want to run stevenson.space locally, make changes, and contribute to the project.
If you’re a student looking to use stevenson.space, visit stevenson.space directly - no installation needed! This guide is specifically for development and contribution.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 16.x or higher recommended

npm

Comes bundled with Node.js

Git

For cloning the repository

Code Editor

VS Code, WebStorm, or your preferred editor

​
Installation Steps

1

Clone the Repository

Clone the stevenson.space repository from GitHub:
git clone https://github.com/stevenson-space/shs.git
cd shs
This creates a local copy of the entire project on your machine.
2

Install Dependencies

Install all required npm packages:
npm install
This installs all dependencies listed in package.json, including:
  • Vue 3 and Vue Router for the framework
  • Pinia for state management
  • Vite for building and dev server
  • TypeScript for type safety
  • FontAwesome for icons
  • And many more development tools
The installation may take a few minutes depending on your internet connection. npm will download over 60 packages including dev dependencies.
3

Configure Environment Variables

Set up your environment configuration:
  1. Duplicate the .env-template file
  2. Rename the duplicate to .env
cp .env-template .env
Your .env file should contain:
.env
VITE_EDIT_COLORS=false
  • VITE_EDIT_COLORS: Set to true if you want to enable color editing features during development
  • The .env file is git-ignored, so your local settings won’t be committed to the repository
  • Vite automatically loads environment variables prefixed with VITE_ and makes them available via import.meta.env
4

Start the Development Server

Launch the Vite development server:
npm run dev
This starts the app at http://localhost:8080 with hot module replacement (HMR) enabled.
VITE v6.4.1  ready in 423 ms

➜  Local:   http://localhost:8080/
➜  Network: use --host to expose
➜  press h + enter to show help
The development server includes hot module replacement, so changes to your code will automatically refresh in the browser without losing application state.
5

Verify Installation

Open your browser and navigate to http://localhost:8080. You should see the stevenson.space home page.Verify that:
  • The page loads without errors
  • Navigation works between routes
  • The theme system is functional
  • Console shows no critical errors (some warnings are normal in development)

​
Project Structure

Understanding the codebase structure will help you navigate and contribute effectively: 
shs/
├── src/
│   ├── views/          # Page components for each route
│   │   ├── Home/       # Home page with schedule dashboard
│   │   ├── Calendar/   # Calendar view
│   │   ├── Settings/   # Settings and theme selection
│   │   └── ...
│   ├── stores/         # Pinia state management stores
│   │   ├── themes.ts   # Theme management
│   │   ├── schedules.ts # Schedule state
│   │   ├── clock.ts    # Time tracking
│   │   └── ...
│   ├── router/         # Vue Router configuration
│   │   └── index.ts    # Route definitions
│   ├── utils/          # Utility functions
│   ├── App.vue         # Root component
│   └── main.ts         # Application entry point
├── public/             # Static assets
├── vite.config.js      # Vite configuration
├── package.json        # Dependencies and scripts
└── tsconfig.json       # TypeScript configuration

​
Available Scripts

Starts the Vite development server at http://localhost:8080 with hot module replacement.
npm run dev
Builds the production-ready application. Runs the event scraper as a prebuild step, then compiles and minifies for deployment.
npm run build
Output is generated in the dist/ directory.
Runs ESLint to check and automatically fix code quality issues in .js, .vue, and .ts files.
npm run lint
Starts Storybook on port 6006 for component development and testing in isolation.
npm run storybook

​
Technology Stack

Vue 3

Progressive JavaScript framework with Composition API

TypeScript

Typed superset of JavaScript for better developer experience

Pinia

Intuitive state management library for Vue

Vite

Next-generation frontend tooling with lightning-fast HMR

Vue Router

Official routing library for single-page applications

Sass

CSS preprocessor for maintainable styles

FontAwesome

Icon library with thousands of icons

Sentry

Error tracking and performance monitoring

​
Code Example: Adding a New Route

Here’s how to add a new page to stevenson.space:
1

Create the Vue Component

Create a new component in src/views/:
src/views/MyNewPage/MyNewPage.vue
<template>
  <div class="my-new-page">
    <h1>My New Page</h1>
    <p>Welcome to my new feature!</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const message = ref('Hello from my new page!');
</script>

<style scoped lang="sass">
.my-new-page
  padding: 2rem
  h1
    color: var(--primary)
</style>
2

Register the Route

Add your route to src/router/index.ts:
src/router/index.ts
import { RouteRecordRaw, RouteComponent } from 'vue-router';

const MyNewPage: RouteComponent = () => import('@/views/MyNewPage/MyNewPage.vue');

const routes: Array<RouteRecordRaw> = [
  // ... existing routes
  {
    name: 'MyNewPage',
    path: '/my-new-page',
    component: MyNewPage,
  },
];
3

Navigate to Your Page

Access your new page at http://localhost:8080/my-new-page or add a navigation link:
Navigation Example
<router-link to="/my-new-page">My New Page</router-link>

​
Contributing Guidelines

Before contributing, please read the contributing documentation on GitHub (work in progress).

​
Best Practices

  1. Run the linter before committing: 
    npm run lint
  2. Test your changes across different routes and themes
  3. Follow TypeScript conventions - use proper types, avoid any
  4. Use Pinia stores for shared state instead of props drilling
  5. Maintain accessibility - ensure keyboard navigation and screen reader support

​
Development Tips

stevenson.space uses Pinia for state management. Example from src/App.vue:
import { mapState, mapActions } from 'pinia';
import useThemeStore from '@/stores/themes';
import useScheduleStore from '@/stores/schedules';

export default {
  computed: {
    ...mapState(useThemeStore, ['styling', 'color']),
  },
  methods: {
    ...mapActions(useScheduleStore, ['initializeSchedule']),
    ...mapActions(useThemeStore, ['initializeTheme']),
  },
};
The project uses @ as an alias for the src/ directory:
// Instead of: import Component from '../../../components/Component.vue'
import Component from '@/components/Component.vue';
Themes use CSS custom properties set in App.vue:24. Access theme colors with:
.my-element {
  color: var(--primary);
  background: var(--background);
  border-color: var(--accent);
}

​
Troubleshooting

If port 8080 is occupied:
  1. Kill the process using port 8080, or
  2. Change the port in vite.config.js:
server: {
  port: 3000, // Use a different port
}
If you see module import errors:
  1. Delete node_modules/ and package-lock.json
  2. Run npm install again
  3. Restart the dev server
For TypeScript-related issues:
  • Ensure you’re using TypeScript 5.3.3 (check package.json)
  • Check tsconfig.json for proper configuration
  • Restart your IDE’s TypeScript server

​
Next Steps

Explore the Codebase

Browse through src/views/ to understand how different pages are built

Check Issues

Visit the GitHub Issues page to find tasks to work on

Join Discussions

Participate in project discussions and planning on GitHub

Submit a PR

Once you’ve made improvements, submit a pull request for review
Questions? Reach out via the GitHub repository or check the /getHelp section in the app for support resources.

Build docs developers (and LLMs) love

Get started for freeTalk to us