Jouw Organisatie Register Site

Introductie

Dit is een starter template voor een register site, gebouwd met Astro. Het is ontworpen om je te helpen snel een register site op te zetten die zoals de register sites van developer.overheid.nl.

Projectstructuur

De mappen-en-bestandsstructuur van dit project is als volgt:

/
├── packages/
│   └── components/
├── public/
├── src/
│   ├── layouts/
│   └── pages/
│       ├── *.astro
│       └── *.md
│   ├── partials/
│   └── types/
└── app.config.ts
└── redocly.yaml
└── package.json

Packages/*

De plek voor eigen packages, zoals unieke componenten. In dit template is er al een voorbeeld components package, maar je kunt er zoveel toevoegen als je wilt.

proprietary

Hier kan je je eigen versie van @developer-overheid-nl/proprietary-example plaatsen.
Doormiddel van een alias in package.json kan je @developer-overheid-nl/proprietary overschrijven. Bijvoorbeeld:

"dependencies": {
  "@developer-overheid-nl/proprietary": "workspace:@your_org_name/proprietary@*",
}

Public

Hier plaats je alle statische assets, zoals afbeeldingen, die je in je site wilt gebruiken.

Layouts

Specifieke layouts kunnen hier worden geplaatst. De layout Markdown.astro staat ook hier (ipv in de layouts package) omdat de Frontmatter in markdown alleen met relatieve paden werkt.

Pages

Astro looks for .astro or .md files in the src/pages/ directory. Each page is exposed as a route based on its file name.

Zie de Astro documentatie voor meer informatie over routing.

Hier zet je de structuur van je site neer. Er is een voorbeeldstructuur opgezet, maar je zal deze natuurlijk aanpassen aan jouw wensen.

Partials

Hier plaats je korte stukjes tekst zoals intro-teksten, disclaimers, etc. Deze kan je dan inladen in je pagina met de volgende syntax:

---
import { Content as Intro } from "../partials/intro.md";
---
<>
  ...
  <Article className="markdown-content utrecht-html" slot="header"><Intro /></Article>
  ...
</>

Types

Het bestand api-schema.ts wordt in deze map gegenereerd.
Eigen Typescript declarations kunnen hier ook toegevoegd worden.

redocly.yaml

Het bestand redocly.yaml bevat de OpenApiSpecification-configuratie van de API. Met pnpm ts:oas wordt een typescript declaration aangemaakt op basis van de OAS.
Hiervoor wordt OpenAPI TypeScript gebruikt en de apps maken gebruik van openapi-fetch waardoor de inhoud van de API direct de correcte types heeft.

app.config.ts

Hier worden algemene instellingen van de app geplaatst, zoals de naam van de app, url's en specifieke taalinstellingen.

Aan de slag

Wil je deze template gebruiken? Volg dan de volgende stappen:

1. Fork deze repository
2. Clone jouw fork lokaal
3. Installeer de dependencies met pnpm install
4. Start de dev server met pnpm dev
5. Open localhost:4321 in je browser

Als de demo site draait, kan je aan de slag met het aanpassen. Zet je eigen organisatiegegevens in app.config.ts, package.json en de README.md. Zoek op @your_org_name, YOUR_ORG_NAME en Jouw Organisatie in de codebase en vervang deze door jouw eigen naam.

De Dingen API lokaal draaien

De demo haalt standaard data op van de Dingen API via my-json-server.typicode.com (zie .env). Is die niet bereikbaar, of wil je de data aanpassen? Draai de API dan lokaal met JSON Server:

1. Clone de API naast deze repository en start de server:

   git clone https://github.com/developer-overheid-nl/dingen-api.git
   cd dingen-api
   pnpm install
   pnpm start

   De API draait nu op http://localhost:3000. Gebruik pnpm start:ro als je alleen GET-verzoeken wilt toestaan; met pnpm start schrijven POST, PATCH en DELETE direct naar db.json.

2. Maak in deze repository een bestand .env.local aan (dit bestand wordt niet gecommit en overschrijft .env):

   API_URL="http://localhost:3000"
   API_ENDPOINT="developer-overheid-nl/dingen-api"

   API_ENDPOINT blijft gelijk aan die in .env: de routes.json van de API stuurt dat pad door naar de juiste resources.

3. Herstart pnpm dev. Env-bestanden worden alleen bij het opstarten ingelezen.

Wil je weer de publieke API gebruiken? Verwijder of hernoem .env.local en herstart pnpm dev.

Heb je openapi.json in de API aangepast? pnpm ts:oas leest de OAS van de main-branch op GitHub (zie redocly.yaml). Genereer de types tot die tijd vanuit de lokale kopie, door het commando in de map dingen-api te draaien:

cd ../dingen-api
../register-site-template/node_modules/.bin/openapi-typescript openapi.json -o ../register-site-template/src/types/api-schema.ts

(Dev)Dependencies

• Astro: Site build, routing, SSR / SSG
• React: Components
• i18Next: Localisation
• Typescript
• OpenAPI TypeScript: Type declarations & fetch
• Biome: formatting, linting and assist

Contact developer.overheid.nl

💬 Slack •  📨 Schiet een issue in •  🔀 Github Discussions •  📜 Bijdragen

---

🧞 Commands

All commands are run from the root of the project, from a terminal:

Command	Action
pnpm install	Installs dependencies
pnpm dev	Starts local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally, before deploying
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm astro -- --help	Get help using the Astro CLI

the Astro documentation.