let's try the `copilot-instructions.md`

copilot-instructions.md

• DIRECTION
  • 🚨 Rules
    • 🚨 always use the "VSCode" to developing this codebase.
    • 🚨 always use the "Angular Commit Format Reference Sheet" to write commit messages.
    • 🚨 in typescript and javascript code use esm format export/import instead of any amd code.
    • 🚨 in typescript and code refactoring change from amd to esm where possible.
    • 🚨 Never add extra comments in the package.json file.
  • ⚡ Refactor
    • ⚡ in node.js version 20 and above, use fileURLToPath to replace **dirname and **filename
    • ⚡ in monorepo, tsconfig.json#compiler.moduleResolution should be Bundler
    • ⚡ in VSCode, remove installation of @astrojs/ts-plugin from tsconfig.json and package.json, use the official Astro extension for VSCode
    • ⚡ in the package.json file, let other contributors know to use pnpm as the package manager
    • ⚡ in the package.json file, if the "exports" field is a conditional reference, then:

DIRECTION

🚨 Rules

🚨 always use the "VSCode" to developing this codebase.

🚨 always use the "Angular Commit Format Reference Sheet" to write commit messages.

🚨 in typescript and javascript code use esm format (export/import) instead of any amd code.

🚨 in typescript and code refactoring change from amd to esm where possible.

🚨 Never add extra comments in the package.json file.

⚡ Refactor

⚡ in node.js version 20 and above, use fileURLToPath to replace __dirname and __filename

• for example

  + import { fileURLToPath } from 'node:url';
  + import path from 'node:path';
  
  + const __filename = fileURLToPath(import.meta.url);
  + const __dirname = path.dirname(fileURLToPath(import.meta.url));

• for example

  // astro.config.mjs
  export default defineConfig({
    vite: {
      resolve: {
        alias: {
  +       demo: fileURLToPath(new URL('./demo', import.meta.url)),
  -       demo: './demo',
        },
      },
    },
  })

⚡ in monorepo, tsconfig.json#compiler.moduleResolution should be Bundler

• modify tsconfig.json

  {
    "extends": "astro/tsconfigs/strictest",
    "compilerOptions": {
      "baseUrl": ".",
  +   "moduleResolution": "Bundler",
      "noUnusedLocals": false,
      "noUnusedParameters": false,
    },
    "include": ["src", "demo", "*.config.*"],
    "exclude": ["node_modules"]
  }

⚡ in VSCode, remove installation of @astrojs/ts-plugin from tsconfig.json and package.json, use the official Astro extension for VSCode

Tip

WHY?

The Astro TypeScript plugin can be installed separately when you are not using the official Astro VS Code extension. This plugin is automatically installed and configured by the VSCode extension, and you do not need to install both.

see https://docs.astro.build/en/guides/typescript/#typescript-editor-plugin

• remove @astrojs/ts-plugin from the tsconfig.json file

  {
    "extends": "astro/tsconfigs/strictest",
    "compilerOptions": {
      "baseUrl": ".",
      "moduleResolution": "Bundler",
      "noUnusedLocals": false,
      "noUnusedParameters": false,
      "paths": {
        "~/*": ["./src/*"]
      },
  -    "plugins": [{ "name": "@astrojs/ts-plugin" }]
    },
    "include": ["src", "*.config.*"],
    "exclude": ["node_modules"]
  }

• remove @astrojs/ts-plugin from package.json dependencies

  • remove by shell

    pnpm remove @astrojs/ts-plugin

  • modify package.json

    {
      "devDependencies": {
        "@astrojs/check": "0.9.4",
        "@astrojs/react": "3.6.2",
        "@astrojs/vercel": "7.8.2",
    -   "@astrojs/ts-plugin": "1.10.4",
        "@types/react": "18.3.12",
        "@types/react-dom": "18.3.1",
        "astro": "4.16.10",
        "react": "18.3.1",
        "react-dom": "18.3.1",
        "typescript": "5.6.3"
      }
    }

⚡ in the package.json file, let other contributors know to use pnpm as the package manager

• pnpm i only-allow -SE

• modify package.json:

  {
    "scripts": {
  +   "preinstall": "npx only-allow pnpm"
    },
    "devDependencies": {
  +   "only-allow": "1.2.1"
    }
  }

⚡ in the package.json file, if the "exports" field is a conditional reference, then:

Tip

why? see https://www.typescriptlang.org/docs/handbook/modules/reference.html#example-explicit-types-condition

Important

📣 you can consider using the command npx publint to check

also see https://github.com/bluwy/publint

• always make sure that "types" is listed first (entry-point for TypeScript resolution - must occur first!)

• always make sure that "default" is listed at the end (as generic fallback that always matches)

• 👍 this is good

  {
    "exports": {
      "./subpath": {
        "import": {
          "types": "./types/subpath/index.d.mts",
          "default": "./es/subpath/index.mjs"
        },
        "require": {
          "types": "./types/subpath/index.d.cts",
          "default": "./cjs/subpath/index.cjs"
        }
      }
    }
  }

• ⛔ this bad

  {
    "exports": {
      "./subpath": {
        "import": {
          "default": "./es/subpath/index.mjs",
          "types": "./types/subpath/index.d.mts"
        },
        "require": {
          "default": "./cjs/subpath/index.cjs",
          "types": "./types/subpath/index.d.cts"
        }
      }
    }
  }