@archpublicwebsite/eslint-config

A reusable ESLint flat config and git-hook toolkit for Archipelago projects.

Overview

@archpublicwebsite/eslint-config ships a flat ESLint config built on @antfu/eslint-config with Vue, TypeScript, Tailwind, and Nuxt-friendly defaults, plus a setup script that bootstraps consuming projects with git hooks, VS Code settings, and security scanning.

Features

• Flat config based on @antfu/eslint-config, tuned for Vue, TypeScript, Tailwind, and Nuxt
• Git hooks for consistent formatting and commit validation
• Automatic project setup on install
• An optional strict commit/push verification mode

Installation

pnpm add -D @archpublicwebsite/eslint-config eslint prettier lint-staged turbo

Installing runs the setup script automatically (see What setup does below). Re-run it manually at any time:

node node_modules/@archpublicwebsite/eslint-config/tools/setup/install.mjs

Quick start

Create or update the root eslint.config.mjs:

import { createArchipelagoConfig } from '@archpublicwebsite/eslint-config'

export default createArchipelagoConfig()

Override rules where your project needs to diverge from the shared defaults:

import { createArchipelagoConfig } from '@archpublicwebsite/eslint-config'

export default createArchipelagoConfig({
  name: 'project/overrides',
  rules: {
    'no-console': 'off',
    'vue/max-attributes-per-line': 'off',
  },
})

Then:

pnpm lint:check
pnpm typecheck

Public API

• createArchipelagoConfig(overrides?) — builds the ESLint flat config.
• Setup and git-hook scripts under tools/ (invoked by the commands below, not imported directly).

createArchipelagoConfig attributes

createArchipelagoConfig(...overrides) accepts one or more flat-config override objects.

Common override attributes:

| Attribute | Type | Purpose | | --- | --- | --- | | name | string | Human-readable config block name for diagnostics. | | files | string[] | Glob scope for rules (for package/app-specific overrides). | | ignores | string[] | Glob exclusions. | | rules | Record<string, any> | ESLint rule overrides. | | plugins | Record<string, Plugin> | Extra plugins for scoped blocks. | | linterOptions | object | Linter behavior flags (for example reportUnusedDisableDirectives). |

Example (scoped override):

import { createArchipelagoConfig } from '@archpublicwebsite/eslint-config'

export default createArchipelagoConfig(
  {
    name: 'project/vue-relaxations',
    files: ['apps/nuxt-web/components/**/*.vue'],
    rules: {
      'vue/max-attributes-per-line': 'off',
    },
  },
)

AI-agent setup checklist

1. Install peer/dev dependencies exactly as documented.
2. Create root eslint.config.mjs using createArchipelagoConfig().
3. Ensure required root scripts exist in package.json.
4. Run setup script once after install (or re-run after repo bootstrap changes).
5. Verify git hooks path is active: git config core.hooksPath should be .hooks.
6. Run pnpm lint:check and pnpm typecheck before committing template updates.

Security behavior summary

This config enforces security-focused defaults for:

1. Injection risks (eval, new Function, implied eval, script URLs).
2. DOM XSS sinks (innerHTML, insertAdjacentHTML, document.write).
3. Prototype-pollution and risky globals/imports.
4. Sensitive imports in build-config files (supply-chain hardening).

If you must diverge, scope exceptions narrowly with files rather than disabling globally.

What setup does

On install, or when you run the setup script manually, the package prepares the consuming project with:

• .hooks/pre-commit, .hooks/prepare-commit-msg, .hooks/commit-msg, .hooks/post-commit
• safe-reinstall.sh (supports --check-only for pre-commit safety checks)
• scan-global.sh, a global IOC scanner
• eslint.config.mjs, if one doesn't already exist
• A .prettierrc entry for prettier-plugin-tailwindcss
• .vscode/settings.json and .vscode/extensions.json with the recommended ESLint flat-config setup
• git config core.hooksPath .hooks, if the project is a git repository

Pre-commit runs, in order: tools/security/scan.mjs, safe-reinstall.sh --check-only (if present), scan-global.sh (if present), then lint-staged. Skip the global machine scan when needed (CI, emergencies) with:

SKIP_GLOBAL_SCAN=1 git commit

Strict commit verification

Set REQUIRE_VERIFIED_ACCOUNT=1 to require a verified git identity on commit/push:

REQUIRE_VERIFIED_ACCOUNT=1 git commit
REQUIRE_VERIFIED_ACCOUNT=1 git push

With this set, pre-commit checks user.name, user.email, and commit.gpgsign=true, and pre-push rejects commits whose signature status isn't G.

Required root scripts

Add these to the consuming project's root package.json:

{
  "scripts": {
    "lint": "pnpm lint:fix",
    "lint:check": "turbo run lint",
    "lint:fix": "((pnpm format || true) && turbo run lint --continue=always -- --fix) || true",
    "precommit": "node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-commit.mjs",
    "security:global-scan": "bash ./node_modules/@archpublicwebsite/eslint-config/tools/security/scan-global.sh",
    "security:safe-check": "bash ./node_modules/@archpublicwebsite/eslint-config/tools/security/safe-reinstall.sh --check-only"
  },
  "lint-staged": {
    "*.{js,ts,tsx,vue}": ["eslint --fix"]
  }
}

Troubleshooting (Nuxt)

If you see Cannot find module '~/composables', Cannot find name 'useRoute' / 'useRuntimeConfig', or '<script setup ...>' expected in .vue files:

1. Confirm the root tsconfig.json extends Nuxt's generated types:

   { "extends": "./.nuxt/tsconfig.json" }

2. Generate the Nuxt type files: npx nuxi prepare

3. Confirm VS Code uses Volar for Vue files (disable Vetur).

4. Re-run the setup script, then restart VS Code (Developer: Reload Window) so the language server picks up the change.

Publishing

cd packages/eslint-config
pnpm version:patch   # or version:minor / version:major
npm pack --dry-run   # confirm the tarball only has eslint.config.mjs, tools/, README.md
npm publish --access public

Contributing

See the root README for contribution guidelines.

License

MIT