Skip to content

Project Creation

The create-astro-project.sh script lives in the ACL repo and generates a complete, ready-to-develop Astro project.

Prerequisites

  • Node.js and npm installed
  • Access to the ACL repo cloned locally
  • Access to the @sitios-agencia-digital GitHub Packages registry (the script creates an .npmrc for this)

Usage

From the parent directory that contains the ACL folder:

chmod +x ACL/scripts/create-astro-project.sh
ACL/scripts/create-astro-project.sh my-new-project

The script will prompt you for:

  1. Project description — a one-line description used for SEO metadata (head.yaml).
  2. Optional integrations — choose between s3, meli, both, or none.

After it finishes, the new project is created as a sibling folder to ACL/.

What the script does

1. Initialize Astro project

  • Runs npm create astro@latest with the minimal template and TypeScript strict mode.
  • Includes a retry mechanism (up to 3 attempts) to handle transient npm errors.

2. Install dependencies

Production and dev dependencies are installed in a single pass:

Category Packages
Core sass, @astrojs/react, @astrojs/tailwind, swiper
Code quality eslint, @typescript-eslint/parser, @typescript-eslint/eslint-plugin, eslint-config-prettier, eslint-plugin-prettier, prettier
Build tools @rollup/plugin-yaml, rimraf, glob
Fonts @fontsource-variable/montserrat, @fontsource-variable/inter
Icons @iconify/react

3. Generate configuration files

The script calls setup-config.sh to create:

File Purpose
astro.config.mjs Site URL, base path, integrations (React, Tailwind, YAML)
tailwind.config.ts Content paths, font families, responsive breakpoints
.eslintrc.json TypeScript ESLint + Prettier integration
.prettierrc.json Formatting rules (semicolons, single quotes, 2-space tabs)
.npmrc GitHub Packages registry auth for @sitios-agencia-digital scope
src/files.d.ts TypeScript declaration for .yaml imports
src/data/head.yaml SEO metadata (title, description, URL)

4. Set up styles (setup-styles.sh)

Creates minimal style files to avoid conflicts:

  • src/styles/global.css — Tailwind directives (@tailwind base/components/utilities)
  • src/styles/_global.scss — CSS resets (box-sizing, margin removal, media defaults)
  • src/styles/_breakpoints.scss — responsive mixins (mobile, tablet, desktop, desktop-lg)

Note

No color, font, or typography files are created automatically. When you start styling, Cursor will prompt you for CSS custom properties and create a _variables.scss file.

5. Set up layouts (setup-layouts.sh)

Creates two layout files:

  • src/layouts/Base.astro — the HTML shell with:

    • <SEO /> component in <head>
    • Preconnect links for Font Awesome, Iconify, jsDelivr, Tally
    • Favicon setup (multiple sizes)
    • Theme color and robots meta
    • Font Awesome Pro Kit script (hardcoded kit code)
    • External scripts (Iconify, isMobile, Tally)

  • src/layouts/SEO.astro — meta tags component:

    • Reads from src/data/head.yaml
    • Open Graph tags (title, description, image, locale)
    • Twitter Card tags
    • Google Tag Manager script

6. Set up utilities (setup-utils.sh)

Always creates:

  • src/utils/buildtime/imageUtils.ts — Astro image processing (glob import → WebP conversion)
  • src/utils/buildtime/index.ts — barrel export

Conditionally creates (based on integration choice):

  • src/utils/buildtime/s3Utils.ts — S3 bucket access via @sitios-agencia-digital/sitios-build-time-sdk
  • src/utils/buildtime/meliUtils.ts — MercadoLibre product fetching via @sitios-agencia-digital/meli-sdk

7. Set up Cursor rules

Copies a general.mdc rule file into .cursor/rules/ that guides AI-assisted development. This rule enforces:

  • Content must live in front.yaml (no hardcoded text)
  • Tailwind for styling
  • TypeScript strict mode with explicit typing
  • Section ID naming conventions
  • Mobile-first responsive design

8. Create GitHub Actions workflow

Creates .github/workflows/deploy.yml that:

  • Triggers on push to master + manual dispatch
  • Uses the reusable workflow from Sitios-Agencia-Digital/workflows
  • Passes secrets: GH_PAT, DISCORD_WEBHOOK
  • If S3 integration is selected: also passes AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and sets the bucket name to sabkt-{project-name}

9. Open in Cursor

If cursor is available in $PATH, the script opens the new project automatically.

Script structure

The main script delegates to four helper scripts:

ACL/scripts/
├── create-astro-project.sh   # Main orchestrator
├── setup-config.sh            # Config files (tailwind, eslint, prettier, npmrc)
├── setup-layouts.sh           # Base.astro + SEO.astro
├── setup-styles.sh            # SCSS files + Tailwind directives
└── setup-utils.sh             # Build-time utilities (images, S3, Meli)

GitHub secrets required

After creating the project, configure these secrets in the GitHub repo:

Secret Required Purpose
GH_PAT Always GitHub Personal Access Token for the reusable workflow
DISCORD_WEBHOOK Always Discord webhook for deploy notifications
AWS_ACCESS_KEY_ID If S3 AWS credentials for S3 bucket access
AWS_SECRET_ACCESS_KEY If S3 AWS credentials for S3 bucket access