[pkg/astro-when]: Implement new package (#68)

.changeset/twelve-rivers-thank.md

@@ -0,0 +1,5 @@
+---
+"@inox-tools/astro-when": minor
+---
+
+Initial release

.github/workflows/example-deploys.yml

@@ -39,6 +39,7 @@ jobs:
         example:
         - sitemap-ext
         - custom-routing
+        - astro-when
     steps:
       - name: Checkout
         uses: actions/checkout@v4

docs/astro.config.ts

@@ -10,6 +10,7 @@ const SITE =
 // https://astro.build/config
 export default defineConfig({
 	site: SITE,
+	trailingSlash: 'never',
 	integrations: [
 		starlight({
 			title: 'Inox Tools',
@@ -34,6 +35,10 @@ export default defineConfig({
 						{
 							label: 'Sitemap Extensions',
 							link: '/sitemap-ext',
+						},
+						{
+							label: 'Astro When',
+							link: '/astro-when',
 							badge: {
 								text: 'NEW',
 								variant: 'success',

docs/src/content/docs/astro-when.md

@@ -0,0 +1,59 @@
+---
+title: Astro When
+packageName: '@inox-tools/astro-when'
+description: Define custom routes and entrypoints in an Astro project without relying on the file-based routing.
+---
+
+This integration provides an import that exposes when in the lifecycle of an Astro codebase your code is running.
+
+When/Where your code is running is made available as an exported constant, so you can change even the exported values of your modules based on it.
+
+## Installing the integration
+
+This integration is needed during build time only, so you can install it as a dev dependency.
+
+```bash title="Installing dependency"
+npm install -D @inox-tools/astro-when
+# OR
+yarn add -D @inox-tools/astro-when
+# OR
+pnpm add -D @inox-tools/astro-when
+```
+
+Then add it to your Astro config:
+
+```ts ins={2,5}
+// astro.config.mjs
+import astroWhen from '@inox-tools/astro-when';
+
+export default defineConfig({
+  integrations: [astroWhen()],
+});
+```
+
+## How to use
+
+Anywhere in your code, be it on a TypeScript file, an Astro component, an MDX file or any UI framework file, you can an import from `@it-astro:when`. This module exports the following:
+
+- An enum `When` defining the constant for each scenario your code might be running.
+- A constant `whenAmI`, which is a value of type `When`.
+
+The possible values are:
+
+- `When.Client`: When your code is running on the client side.
+- `When.Server`: When your code is running on a prod server serving an SSR route.
+- `When.Prerender`: When your code is running during build to prerendeer a route on a project outputing for an SSR runtime.
+- `When.StaticBuild`: When your code is running during build to prerender a route on a project that is entirely static (no SSR adapter and `output: 'static'`).
+- `When.DevServer`: When your code is running on the server during development.
+
+:::note
+`astro preview` is intended to behave as a prod server, so instead of exposing that as `When.PreviewServer` it is intentionally exposed as `When.Server`.
+:::
+
+## Example
+
+You can check [this example](https://github.com/Fryuni/inox-tools/tree/main/examples/astro-when) on when each value shows up. You can also see it in action on a deployment of that same example [here](https://inox-tools-ex-astro-when.pages.dev/).
+
+## License
+
+Astro When is available under the MIT license.

examples/astro-when/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

examples/astro-when/README.md

@@ -0,0 +1,47 @@
+# Astro Starter Kit: Minimal
+
+```sh
+npm create astro@latest -- --template minimal
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/minimal)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/minimal)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/minimal/devcontainer.json)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro project, you'll see the following folders and files:
+
+```text
+/
+├── public/
+├── src/
+│   └── pages/
+│       └── index.astro
+└── package.json
+```
+
+Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.
+
+There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.
+
+Any static assets, like images, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).

examples/astro-when/astro.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'astro/config';
+import astroWhen from '@inox-tools/astro-when';
+
+import node from '@astrojs/node';
+
+// https://astro.build/config
+export default defineConfig({
+	integrations: [astroWhen()],
+	output: 'server',
+	adapter: node({
+		mode: 'standalone',
+	}),
+});

examples/astro-when/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@examples/astro-when",
+  "private": true,
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro check && astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/check": "^0.5.10",
+    "@astrojs/node": "^8.2.5",
+    "@inox-tools/astro-when": "workspace:^",
+    "astro": "^4.5.16",
+    "typescript": "^5.4.4"
+  }
+}

examples/astro-when/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="astro/client" />

examples/astro-when/src/middleware.ts

@@ -0,0 +1,28 @@
+import { whenAmI, When } from '@it-astro:when';
+import type { MiddlewareHandler } from 'astro';
+
+const middlewares: Record<When, MiddlewareHandler> = {
+	[When.Client]: () => {
+		throw new Error('Client should not run a middleware!');
+	},
+	[When.DevServer]: (_, next) => {
+		console.log('Running middleware on dev server');
+		return next();
+	},
+	[When.Server]: (_, next) => {
+		console.log('Running middleware on server for a server route');
+		return next();
+	},
+	[When.Prerender]: (_, next) => {
+		console.log('Running middleware while prerendering a route during build for an SSR output');
+		return next();
+	},
+	[When.StaticBuild]: (_, next) => {
+		console.log(
+			'Running middleware while rendering a route during build for a fully static output'
+		);
+		return next();
+	},
+};
+
+export const onRequest = middlewares[whenAmI];

examples/astro-when/src/pages/index.astro

@@ -0,0 +1,30 @@
+---
+import { whenAmI } from '@it-astro:when';
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro When</title>
+	</head>
+	<body>
+		<h1>Astro</h1>
+		<p>Running on: {whenAmI}</p>
+		<hr />
+		<p>Other pages:</p>
+		<ul>
+			<li><a href="/prerender/">Opting in to prerendering</a></li>
+			<li><a href="/on-demand/">Opting out of prerendering</a></li>
+		</ul>
+		<hr />
+		<p id="clientRender"></p>
+	</body>
+</html>
+
+<script>
+	import { whenAmI } from '@it-astro:when';
+
+	document.getElementById('clientRender')!.textContent = `Client render: ${whenAmI}`;
+</script>

examples/astro-when/src/pages/on-demand.astro

@@ -0,0 +1,32 @@
+---
+import { whenAmI } from '@it-astro:when';
+
+export const prerender = false;
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro When</title>
+	</head>
+	<body>
+		<h1>Opting out of prerendering</h1>
+		<p>Running on: {whenAmI}</p>
+		<hr />
+		<p>Other pages:</p>
+		<ul>
+			<li><a href="/">Home</a></li>
+			<li><a href="/prerender/">Opting in to prerendering</a></li>
+		</ul>
+		<hr />
+		<p id="clientRender"></p>
+	</body>
+</html>
+
+<script>
+	import { whenAmI } from '@it-astro:when';
+
+	document.getElementById('clientRender')!.textContent = `Client render: ${whenAmI}`;
+</script>

examples/astro-when/src/pages/prerender.astro

@@ -0,0 +1,32 @@
+---
+import { whenAmI } from '@it-astro:when';
+
+export const prerender = true;
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro When</title>
+	</head>
+	<body>
+		<h1>Opting in to prerendering</h1>
+		<p>Running on: {whenAmI}</p>
+		<hr />
+		<p>Other pages:</p>
+		<ul>
+			<li><a href="/">Home</a></li>
+			<li><a href="/on-demand/">Opting out of prerendering</a></li>
+		</ul>
+		<hr />
+		<p id="clientRender"></p>
+	</body>
+</html>
+
+<script>
+	import { whenAmI } from '@it-astro:when';
+
+	document.getElementById('clientRender')!.textContent = `Client render: ${whenAmI}`;
+</script>

examples/astro-when/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "exclude": ["node_modules", "dist"]
+}

packages/astro-when/README.md

@@ -0,0 +1,11 @@
+<p align="center">
+    <img alt="InoxTools" width="350px" src="https://github.com/Fryuni/inox-tools/blob/main/assets/shield.png?raw=true"/>
+</p>
+
+# Astro When
+
+Integration that informs when in Astro's lifecycle the code is running.
+
+### License
+
+Astro Sitemap Extended is available under the MIT license.

packages/astro-when/gitignore

@@ -0,0 +1,3 @@
+node_modules
+*.log
+lib

packages/astro-when/npmignore

@@ -0,0 +1,3 @@
+node_modules
+*.log
+src