Flailingwords Astro Template

Create a new project using the command below:

pnpm create astro@latest -- --template forge.interspatial.ca/flailingwords/template-astro

✨ Features

• Astro
• React
• Tailwind
• Typescript
• just based tool-chain
• wireit
• Opinionated eslint and prettier configs
• editorconfig

🚀 Project Structure

Inside of your Astro project, you'll see the following folders and files:

/
├── public/
├── src/
│   └── lib/
│       └── !index.ts
│   └── pages/
│       └── index.astro
│   └── schemas/
│       └── !index.ts
│       └── !guards.ts
│       └── !types.ts
└── 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.

Any shared library code can be put in files in the src/lib/ directory. index.ts is reserved as it will be automatically generated.

Any (astro/)zod schemas can be stored in the src/schemas directory in files other than index.ts, guards.ts and types.ts, as they are automatically generated based on the exports.

lib and schemas

schemas

This template uses the zCamelCase name convention for schemas.

For example: We create a src/schemas/utils.ts with the content below:

import { z } from 'astro/zod'

export const zString = z.string().min(5)

After we run just build-schemas, we will have the following files and contents:

src/schemas/guards:

/*
 * DO NOT EDIT! THIS FILE IS GENERATED!
 */
import type { String } from './types.js'

import { zString } from './utils.js'

export const isString = (inp?: unknown): inp is String => zString.safeParse(inp).success

src/schemas/types.ts:

/*
 * DO NOT EDIT! THIS FILE IS GENERATED!
 */
import type { z } from 'astro/zod'

import type { zString } from './utils.js'

export type String = z.infer<typeof zString>

indexes

Indexes are generated for the lib and schemas directory by running just build-indexes.

For the example above, it will create the following index.ts file:

src/schemas/index.ts:

/*
 * DO NOT EDIT! THIS FILE IS GENERATED!
 */
export * from './guards.js'
export type * from './types.js'
export * from './utils.js'

As you can see, it will export both the generated guards and types files, as well as the definition file itself.

🧞 Commands

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

Command	Action
pnpm astro -- --help	Get help using the Astro CLI
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm build	Build your production site to ./dist/ type-check, lint and format are ran in the process of this.
pnpm dev:lan	Starts local dev server on all network interfaces
pnpm dev	Starts local dev server at localhost:4321
pnpm format	Format all files
pnpm install	Installs dependencies
pnpm just	This will show all available options in the justfile. Equivalent to pnpm just help pnpm just -l.
pnpm lint	Lint all src files
pnpm preview	Preview your build locally, before deploying
pnpm type-check	Type check all Typescript files

Building

There are two ways to build:

• the cached/wireit way
• the just way

This template uses both to optimize build abstraction while at the same time use wireit's caching mechanisms.

By using just to abstract the underlying commands, the wireit configuration remains stable and as only the justfile gets updated, doing so will avoid full rebuilds and allow this template be more selective in its builds.

Wireit (cached)

This project uses wireit, which allows for cache control of the build chain. In other words, it can monitor the state of the files and only selectively build based on whether the input files for a particular step have changed.

E.g. If the schema files have not changed, then the the build:schemas and build:schemas-index steps will not run.

wireit is configured through the package.json file, but uses just commands in the background.

just

Behind every script command is a just command/command chain.

While the build script uses a fully qualified dependency graph to express its dependencies structure to allow wireit to optimize and parallelize execution, the main just commands use flat serial dependencies that may be executed in parallel if explicitly configured to do so.

Example:

build: build-astro-sync build-schemas build-indexes build-lint build-format build-type-check build-dist

The just build command has the following dependencies:

• build-astro-sync
• build-schemas
• build-indexes*
• build-lint
• build-format
• build-type-check
• build-dist

The build-indexes definition is defined to be ran in parallel, but otherwise, just will always execute every step without regard to cache status.

👀 Want to learn more?

Feel free to check the Astro documentation or jump into the Astro Discord server.