aqzhyi/copilot-instructions.md

## copilot-instructions.md

      
    Raw
  

              copilot-instructions.md
            
          
📖 in node.js version 20 and above

🚥 Rules

🚥 when you need to resolve a file path, use fileURLToPathnew URLrelativePath, import.meta.url
🚥 when importing native node.js modules, use the node: protocol


📖 in typescript and javascript

🚥 Rules


📖 in Git Commit Message

🚥 Rules

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


📖 in package.json file

🚥 Rules

🚥 never add extra comments in the package.json file.
🚥 if the "exports" field is a conditional reference, then:


💡 Tasks

💡 if you say: refactor it to ESM module
💡 if you say: refactor the order of the keys


📖 in next@^15 with App-Router

💡 Tasks

💡 if you say: install chakra-ui@^3
💡 if you say: eject the default theme of chakra-ui@^3


📖 in astro@^4 and astro@^5

🚥 Tasks

🚥 if you say: refactor for @astrojs/ts-plugin


📖 Common Tasks

🚥 Tasks

🚥 if you say: auto load .env or install dotenv


📖 in node.js version 20 and above

🚥 Rules

🚥 when you need to resolve a file path, use fileURLToPath(new URL(relativePath), import.meta.url)

🚥 when importing native node.js modules, use the node: protocol


📖 in typescript and javascript

🚥 Rules


🚥 always use esm format (export/import) as the main module system, instead of amd and commonjs (cjs) code.


🚥 the value of compiler.moduleResolution in the tsconfig.json file should be Bundler
{
  "compilerOptions": {
+   "moduleResolution": "Bundler",
  },
}


📖 in Git Commit Message

🚥 Rules

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

Note
also see https://www.conventionalcommits.org/


📖 in package.json file

🚥 Rules

🚥 never add extra comments 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)

💡 Tasks

💡 if you say: refactor it to ESM module


there must be a type field, and its value should be "module".
remove the main, module, and types fields.
there must be an "exports" field.

for example:
{
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "default": "./index.cjs"
+    }
+  },
-  "main": "./index.cjs",
-  "module": "./index.mjs",
-  "types": "./index.d.ts",
}
💡 if you say: refactor the order of the keys


just reorder the keys in the file, do not change the values of the keys


the order of the keys should be as follows:

license
private
name
version
description
files
exports
author
repository
homepage
bugs
peerDependencies
dependencies
devDependencies
keywords
scripts


📖 in next@^15 with App-Router

💡 Tasks

💡 if you say: install chakra-ui@^3

Tip
also see chakra-ui get-started


run in the terminal pnpm add @chakra-ui/react @emotion/react -S as dependencies


run in the terminal pnpm add @chakra-ui/cli -D as devDependencies


add the following script in package.json#scripts
{
  "scripts": {
+    "chakra": "chakra"
  }
}


find the <html></html> element in the ./app/layout.{tsx,jsx} file and add the suppressHydrationWarning attribute to it
<html
  lang='en'
+ suppressHydrationWarning
>


💡 if you say: eject the default theme of chakra-ui@^3


if the ./@chakra-ui/theme folder already exists, skip the steps below
you run pnpm chakra eject --outdir @chakra-ui/theme in the project folder to create the default theme design and components


📖 in astro@^4 and astro@^5

🚥 Tasks

🚥 if you say: refactor for @astrojs/ts-plugin

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, for example:
{
  "compilerOptions": {
    "baseUrl": ".",
    "plugins": [
-     { "name": "@astrojs/ts-plugin" },
      { "name": "other-ts-plugin" }
    ]
  }
}


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


run pnpm remove @astrojs/ts-plugin in the terminal


📖 Common Tasks

🚥 Tasks

🚥 if you say: auto load .env or install dotenv

please follow the steps below:


add package dotenv to the devDependencies of package.json
pnpm add dotenv -D


introduce and call the dotenv.config() method where needed
import 'dotenv/config'


make sure the env.d.ts file exists. if it does not, create one in the ./app or ./src folder


make sure env.d.ts is list in the include field of tsconfig.json


make sure the env.d.ts has following code is there
interface EnvVarables {
  // VITE_ENV_VARIABLE1: string
  // VITE_ENV_VARIABLE2: string
}

declare namespace NodeJS {
  interface ProcessEnv extends EnvVarables {}
}

interface ImportMeta {
  readonly env: EnvVarables
}