Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/FUNDING.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,6 @@ lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cl
polar: # Replace with a single Polar username
buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
thanks_dev: # Replace with a single thanks.dev username
custom: ['https://www.betterplace.org/en/projects/89947-opensensemap-org-the-free-map-for-environmental-data'] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
custom: [
'https://www.betterplace.org/en/projects/89947-opensensemap-org-the-free-map-for-environmental-data',
] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
18 changes: 9 additions & 9 deletions .github/dependabot.yaml
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
version: 2

updates:
- package-ecosystem: "github-actions"
directory: "/"
- package-ecosystem: 'github-actions'
directory: '/'
schedule:
interval: "weekly"
- package-ecosystem: "docker"
directory: "/"
interval: 'weekly'
- package-ecosystem: 'docker'
directory: '/'
schedule:
interval: "weekly"
- package-ecosystem: "npm"
directory: "/"
interval: 'weekly'
- package-ecosystem: 'npm'
directory: '/'
schedule:
interval: "weekly"
interval: 'weekly'
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ jobs:
# the sleep is just there to give time for postgres to get started
run: docker compose -f docker-compose.ci.yml up -d && sleep 30
env:
DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/postgres"
DATABASE_URL: 'postgresql://postgres:postgres@localhost:5432/postgres'

- name: 🛠 Setup Database
uses: nick-fields/retry@v3.0.2
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/purge-pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,4 @@ jobs:
organization: ${{ github.repository_owner}}
container: ${{ github.event.repository.name }}
tag-regex: pr-${{github.event.pull_request.number}}$
dry-run: false
dry-run: false
4 changes: 2 additions & 2 deletions .github/workflows/purge.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: 🗑️ Purge untagged images
on:
schedule:
- cron: "0 0 * * *"
- cron: '0 0 * * *'

permissions:
packages: write
Expand All @@ -16,4 +16,4 @@ jobs:
token: ${{ secrets.GITHUB_TOKEN }}
organization: ${{ github.repository_owner}}
container: ${{ github.event.repository.name }}
prune-untagged: true
prune-untagged: true
4 changes: 2 additions & 2 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,5 @@ node_modules
.env

/postgres-data

/app/styles/**/*.css
/db/seeds/**/*
/drizzle/**/*
111 changes: 76 additions & 35 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
![openSenseMap](https://github.com/openSenseMap/frontend/blob/dev/public/openSenseMap.png)

This repository contains the code of the new _openSenseMap_ frontend running at [https://beta.opensensemap.org](https://beta.opensensemap.org).
This repository contains the code of the new _openSenseMap_ frontend running at
[https://beta.opensensemap.org](https://beta.opensensemap.org).

Originally, the _openSenseMap_ was built as part of the bachelor thesis of [@mpfeil](https://github.com/mpfeil) at the ifgi (Institute for Geoinformatics, University of Münster). Between 2016 and 2022 development was partly funded by the German Ministry of Education and Research (BMBF) in the projets senseBox and senseBox Pro. This version has been developed by [@mpfeil](https://github.com/mpfeil) and [@freds-dev](https://github.com/freds-dev).
Originally, the _openSenseMap_ was built as part of the bachelor thesis of
[@mpfeil](https://github.com/mpfeil) at the ifgi (Institute for Geoinformatics,
University of Münster). Between 2016 and 2022 development was partly funded by
the German Ministry of Education and Research (BMBF) in the projets senseBox and
senseBox Pro. This version has been developed by
[@mpfeil](https://github.com/mpfeil) and
[@freds-dev](https://github.com/freds-dev).

<img width="1438" alt="Screenshot OSeM" src="https://github.com/user-attachments/assets/a7bf16fb-44a2-4a21-9c0f-d4bf431ab9b5">

## Project setup

If you do need to set the project up locally yourself, feel free to follow these instructions:
If you do need to set the project up locally yourself, feel free to follow these
instructions:

### System Requirements

Expand All @@ -19,7 +27,8 @@ If you do need to set the project up locally yourself, feel free to follow these

### Variables

You can configure the API endpoint and/or map tiles using the following environmental variables:
You can configure the API endpoint and/or map tiles using the following
environmental variables:

| ENV | Default value |
| ------------------- | ------------------------------------ |
Expand All @@ -34,23 +43,28 @@ You can create a copy of `.env.example`, rename it to `.env` and set the values.
1. Clone the repo: `git clone https://github.com/openSenseMap/frontend`
2. Copy `.env.example` into `.env`
3. Run `npm install` to install dependencies
4. Optionally run `docker compose up` to start a docker container running your local postgres DB
- If it is the first time doing this, you may need to bootstrap the database by running `npm run db:setup`
- If you want some example data run `npm run db:seed`. **WARNING**: Do not run this on a production database. It will delete all existing data.
4. Optionally run `docker compose up` to start a docker container running your
local postgres DB
- If it is the first time doing this, you may need to bootstrap the database
by running `npm run db:setup`
- If you want some example data run `npm run db:seed`. **WARNING**: Do not
run this on a production database. It will delete all existing data.
5. Run `npm run dev` to start the local server

### Contributing

We welcome all kind of constructive contributions to this project.
If you are planning to implement a new feature or change something, please create an issue first.
We welcome all kind of constructive contributions to this project. If you are
planning to implement a new feature or change something, please create an issue
first.

Afterwards follow these steps:

1. Fork this repository
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Make and commit your changes
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new pull request against this repository's `dev` branch, linking your issue.
5. Create a new pull request against this repository's `dev` branch, linking
your issue.

#### How the repository is organized

Expand All @@ -75,18 +89,39 @@ Afterwards follow these steps:

#### openSenseMap API

The api is implemented using [Remix resource routes](https://remix.run/docs/en/main/guides/resource-routes).
Resource routes may not export a component but only [loaders](https://remix.run/docs/en/main/route/loader) (for `GET` requests) and [actions](https://remix.run/docs/en/main/route/action) (for `POST`, `PUT`, `DELETE` etc) and therefore live in `.ts` (not `.tsx`) files.
All resource routes start with `api` (e.g. `api.user.ts` for `/api/user`).

The api logic is shared with the frontend. Therefore api routes should not implement the actual business logic of an endpoint. They are responsible for checking the request for validity and for transforming the data into the correct output format.
Logic should be implemented in corresponding services, that may be used by loaders/ actions of page routes that access the same functionality.

For example: User registration is possible from both the api and the frontend. The logic for it is implemented in `lib/user.service.ts` and it is being used by both `api.user.ts` (resource route) as well as `explore.register.tsx` (page route), preventing duplication of common logic while also providing the flexibility to adjust the outputs to the needs of the respective use case.
The api is implemented using
[Remix resource routes](https://remix.run/docs/en/main/guides/resource-routes).
Resource routes may not export a component but only
[loaders](https://remix.run/docs/en/main/route/loader) (for `GET` requests) and
[actions](https://remix.run/docs/en/main/route/action) (for `POST`, `PUT`,
`DELETE` etc) and therefore live in `.ts` (not `.tsx`) files. All resource
routes start with `api` (e.g. `api.user.ts` for `/api/user`).

The api logic is shared with the frontend. Therefore api routes should not
implement the actual business logic of an endpoint. They are responsible for
checking the request for validity and for transforming the data into the correct
output format. Logic should be implemented in corresponding services, that may
be used by loaders/ actions of page routes that access the same functionality.

For example: User registration is possible from both the api and the frontend.
The logic for it is implemented in `lib/user.service.ts` and it is being used by
both `api.user.ts` (resource route) as well as `explore.register.tsx` (page
route), preventing duplication of common logic while also providing the
flexibility to adjust the outputs to the needs of the respective use case.

##### Documenting an API Route

The [swaggerJsdoc Library](https://www.npmjs.com/package/swagger-jsdoc) reads the JSDoc-annotated source code in the api-routes and generates an openAPI(Swagger) specification and is rendered using [Swaggger UI](https://swagger.io/tools/swagger-ui/). The [JSDoc annotations](https://github.com/Surnet/swagger-jsdoc) is usually added before the loader or action function in the API Routes. The documentation will then be automatically generated from the JSDoc annotations in all the api routes. When testing the api during development do not forget to change the server to [Development Server](http://localhost:3000). To authorize a user you must provide the token obtained after sign-in. You can just copy and paste the token in the value field and then hit the authorize button.
The [swaggerJsdoc Library](https://www.npmjs.com/package/swagger-jsdoc) reads
the JSDoc-annotated source code in the api-routes and generates an
openAPI(Swagger) specification and is rendered using
[Swaggger UI](https://swagger.io/tools/swagger-ui/). The
[JSDoc annotations](https://github.com/Surnet/swagger-jsdoc) is usually added
before the loader or action function in the API Routes. The documentation will
then be automatically generated from the JSDoc annotations in all the api
routes. When testing the api during development do not forget to change the
server to [Development Server](http://localhost:3000). To authorize a user you
must provide the token obtained after sign-in. You can just copy and paste the
token in the value field and then hit the authorize button.

##### JSDoc Example

Expand Down Expand Up @@ -144,29 +179,35 @@ Here's an example of how to document an API route using JSDoc annotations:
* description: Internal server error
*/
export async function loader({ params }) {
const { id } = params;

try {
const user = await getUserById(id);
if (!user) {
throw new Response("User not found", { status: 404 });
}
return Response.json({ user });
} catch (error) {
throw new Response("Internal server error", { status: 500 });
}
const { id } = params

try {
const user = await getUserById(id)
if (!user) {
throw new Response('User not found', { status: 404 })
}
return Response.json({ user })
} catch (error) {
throw new Response('Internal server error', { status: 500 })
}
}
```

This JSDoc annotation will automatically generate comprehensive API documentation including endpoint details, parameters, response schemas, and example values.
This JSDoc annotation will automatically generate comprehensive API
documentation including endpoint details, parameters, response schemas, and
example values.

#### Testing

Tests are placed in the [tests/](./tests/) folder whose structure is similar to the [app/](./app/) folder.
When adding a test, use the same name as the file you are testing but change the file extension to `.spec.ts`, e.g. when creating tests for [`./app/utils`](./app/utils.ts) name the test file [`./tests/utils.spec.ts`](./tests/utils.spec.ts).
Tests are placed in the [tests/](./tests/) folder whose structure is similar to
the [app/](./app/) folder. When adding a test, use the same name as the file you
are testing but change the file extension to `.spec.ts`, e.g. when creating
tests for [`./app/utils`](./app/utils.ts) name the test file
[`./tests/utils.spec.ts`](./tests/utils.spec.ts).

To run the tests, make sure you have a working database connection (e.g. by running `docker compose up` with the corresponding environment variables to use your local database).
Then simply run `npm test`.
To run the tests, make sure you have a working database connection (e.g. by
running `docker compose up` with the corresponding environment variables to use
your local database). Then simply run `npm test`.

## License

Expand Down
Loading
Loading