KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #react #mcp #open-source #deepseek-harness #dsh-plugin #ai

tycho

★ 113 Open GitHub ↗

🪐 A real-time interactive simulation of the solar system.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h3 align="center"><a href="https://tycho.io">Tycho.io</a></h3>

A real-time interactive simulation of the solar system.

## Development

<details>
 <summary>Quick start</summary>

1. Clone this repo:

```sh
git clone https://github.com/jshor/tycho.git
```

2. Use the right node version:

```sh
nvm use
```

3. Install dependencies (via [Yarn](https://yarnpkg.com/en/)):

```sh
yarn
```

4. Start:

```sh
yarn start
```

</details>

<details>
 <summary>Framework and libraries</summary>

This app is written in [TypeScript](https://www.typescriptlang.org/) and built using [React.js](https://react.dev/), [THREE.js](https://threejs.org), and [zustand](https://github.com/pmndrs/zustand) for state. It uses [react-three-fiber](https://github.com/pmndrs/react-three-fiber) for THREE-based React components, along with its [drei](https://github.com/pmndrs/drei) helpers. It's bundled using [Vite](https://vite.dev/).
</details>

<details>
 <summary>Styling</summary>

Each DOM component contains a corresponding [Sass](http://sass-lang.com/) stylesheet and employs the [BEM](http://getbem.com/) CSS design pattern. Vite compiles the Sass as part of the build.
</details>

<details>
 <summary>Application Architecture</summary>

The overall architecture follows a container pattern, split between `src/modules` and `src/components`. In a nutshell, modules in this app leverage tasks such as handling state and minor front-end logic, while components simply handle the presentation. Physics calculations and business logic is delegated to services, and some critical components, such as the Camera, have dedicated services.
</details>

<details>
 <summary>State management</summary>

All shared-state data is stored in the [zustand](https://github.com/pmndrs/zustand) store, which lives in `src/store`. This includes the 2D and 3D positions of objects and the current time. Modules subscribe to the slices they need and the store is written to through its actions, which keeps the data flowing in one direction. In rare cases, some components will use the local state for things internal to that component, when appropriate.
</details>

<details>
 <summary>File structure</summary>

This project utilizes a typical React app flat directory structure. Tests for each item typically live in `__tests__`. Components have corresponding tests and Sass in the same directory. `__tests__` folders may contain `__fixtures__`.

The source is laid out as follows:

| Path             | Contents                                                           |
| ---------------- | ------------------------------------------------------------------ |
| `src/modules`    | Logical components that hold state and front-end logic             |
| `src/components` | Presentational components with styling                             |
| `src/utils`      | Functional utilities and helpers, including for math and physics   |
| `src/store`      | The Zustand store shared across the app                            |
| `src/shaders`    | GL fragment and vertex shaders for the scene                       |
| `src/elements`   | Scene aids, such as the clock, camera controls, and ambience audio |
| `src/constants`  | Tunable values for the scene, the UI, and the tour                 |
| `src/test`       | Test setup and utilities                                           |

Note that 3D React components and `DOMElement` ones coexist in the same general paths.

Static assets, such as textures, media, and data are stored in the `public` folder. Some JSON file contents are generated by build scripts.

</details>

<details>
 <summary>Running the project</summary>

In the project directory, you can run the following commands:

### `yarn start`

Runs the app in the development mode. 
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.

The page will hot reload if you make edits. 
</details>

<details>
 <summary>Unit testing</summary>

Tests use [Vitest](https://vitest.dev/) and [Testing Library](https://testing-library.com/docs/react-testing-library/intro), running against [jsdom](https://github.com/jsdom/jsdom). Shared setup lives in `src/test`, which stubs the browser APIs jsdom lacks and stands in for react-three-fiber, so that scene code can be rendered and asserted on without a WebGL context.

### `yarn test`

Runs the whole test suite once, as CI does.

### `yarn test:watch`

Launches the test runner in the interactive watch mode.

### `yarn test:coverage`

Runs all tests and prints out code covfefe. 
</details>

<details>
 <summary>Linting and formatting</summary>

### `yarn lint`

Runs the linter using [ESLint](https://eslint.org/), configured in flat format in `eslint.config.cjs`.

Note that the project compiles with TypeScript 7, while typescript-eslint still requires the TypeScript 6 API. Both are installed side by side for that reason: `typescript` is the compiler, and the `typescript-6` alias exists only so the linter can parse. The config seeds the former with the latter, and both it and the extra dependency can go once typescript-eslint supports TypeScript 7.

### `yarn lint:fix`

Fixes any linting errors discovered by the linter and reports any issues that could not be addressed automatically.

### `yarn typecheck`

Type checks the project without emitting anything.

### `yarn format`

Formats the project using [Prettier](https://prettier.io/). Use `yarn format:check` to report on formatting without writing any changes. 
</details>

<details>
 <summary>Building</summary>

### `yarn build`

Type checks the project and builds the app for production to the `dist` folder. 
It correctly bundles React in production mode and optimizes the build for the best performance. 
The build is minified and the filenames include the hashes.

### `yarn preview`

Serves the built `dist` folder locally, to check a production build before it ships.
</details>

<details>
 <summary>Maintaining ephemerides</summary>

### Ephemerides

Ephemerides are all of the orbital characteristic data points used to aid in the computation of celestial positions of orbital bodies.

For information on the file structure for these JSON files, please see the [Wiki](https://github.com/jshor/tycho2/wiki/Orbital-JSONs).

The maintainable versions of all orbital data (including their ephemerides) are stored in `public/static/data/orbitals/{heliocentric-system}/{satellite-or-barycentric-orbital}.json`.

### Example folder structure

- `public/static/data/orbitals/`
  - `earth/`
    - `earth.json`
    - `moon.json`

### Updating ephemerides

**`yarn ephemerides`**

Takes all orbital JSONs, probes the [JPL Horizons database](https://horizons.jpl.nasa.gov/) for ephemerides, and updates each JSON accordingly. For more information on this script, and on the prerequisite data format, please see [this wiki page](https://github.com/jshor/tycho2/wiki/Orbital-JSONs#nasa-jpl-horizons).

## Building the main orbitals file

The main `orbitals.json` file in `public/static/data` is a compilation of all the orbital JSONs. It is a flat array of all the orbitals in the Solar System scene, including all planets and satellites.

**`yarn ephemerides:build`**

Compiles the `orbitals.json` file. This is also run as part of `yarn build`.
</details>

<details>
 <summary>Deployment</summary>

### Deployment

Deployment is handled by [GitHub Actions](https://github.com/jshor/tycho/actions), defined in `.github/workflows/merge.yml`. On every push to `main`, the workflow lints the project, runs the tests with coverage, reports that coverage to [Codecov](https://app.codecov.io/gh/jshor/tycho.io/tree/main), and builds the app. The resulting `dist` folder is then published to the `gh-pages` branch, along with a `CNAME` pointing at [tycho.io](https://tycho.io).
</details>

## Credits

- Project developed by [Josh Shor](http://josh.so)
- Planetary ephemerides courtesy of [NASA](https://jpl.nasa.gov/) and the [Jet Propulsion Laboratory](https://www.nasa.gov/).
- Orbital textures by [James Hastings-Trew](http://planetpixelemporium.com/).
- Ambient music: [_Ultra Deep Field_](https://soundcloud.com/stellardrone/stellardrone-ultra-deep-field) by [Stellardrone](https://soundcloud.com/stellardrone).
- Special thanks to the open source community for [React.js](https://react.dev/), [THREE.js](https://threejs.org), and [react-three-fiber](https://github.com/pmndrs/react-three-fiber).

tycho

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README