ASIDE v1.5.0 Migration Guide

ASIDE v1.5.0 への移行ガイド

English follows Japanese.

概要

ASIDE の バージョン v1.5.0 未満は以下の問題があった。

  • ESlint の config が .eslintrc.json 形式のままだった
    • ESlint は v9 系から Flat Config 形式を推奨しているが、未対応
    • v8 系の 8.57.1 で止まっていた
  • gts の互換性がなくなっていた
    • gts 7.0.0 から ESlint の 9.37.0 が採用されているが、上記の理由で lint コマンドが失敗する

ASIDE 1.5.0 は、eslint.config.js 等を提供するようになったため、「新しいプロジェクトを作る」場合は問題ない。
既存の v1.4.6 以下（1.5.0未満）のプロジェクトを v1.5.0 以上にアップデートする場合にどのようにすれば良いか、実際にアップデートした際の手順をまとめる。

ファイルの準備

tsconfig.json の更新

変更点:

  • "moduleResolution": "bundler", に変更
  • "lib": ["es2020", "dom"], となり "dom" が追加
  • "types": ["jest", "node", "google-apps-script"] が追加
--- tsconfig.json       2025-07-26 18:54:37.959618437 +0900
+++ ../aside_v1.5.0_test/tsconfig.json  2026-06-20 12:57:13.365750560 +0900
@@ -2,8 +2,8 @@
   "compilerOptions": {
     "target": "es2020",
     "module": "es2020",
-    "lib": ["es2020"],
-    "moduleResolution": "node",
+    "lib": ["es2020", "dom"],
+    "moduleResolution": "bundler",
     "outDir": "dist",
     "rootDir": ".",
     "strict": true,
@@ -12,7 +12,8 @@
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
     "allowUnreachableCode": false,
-    "allowUnusedLabels": false
+    "allowUnusedLabels": false,
+    "types": ["jest", "node", "google-apps-script"]
   },
   "include": ["src/**/*", "test/**/*", "rollup.config.mjs"]
 }

.eslintrc.json から eslint.config.js への移行

.eslintrc.json を削除し、以下の内容で eslint.config.js を作成する。必要に応じて内容を変更する。

{
  "env": {
    "browser": true,
    "node": true,
    "es2020": true
  },
  "extends": ["./node_modules/gts", "prettier"],
  "overrides": [],
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "project": "./tsconfig.json"
  },
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  },
  "ignorePatterns": ["template/**/*", "template-ui/**/*"]
}

のような形式であった。

  • env, plugins 部分は削除
  • project はそのまま
  • gts は extends の代わりに require
  • ignorePatterns は、eslint.ignores.js に移動（後述）
let customConfig = [];
let hasIgnoresFile = false;
try {
  require.resolve('./eslint.ignores.cjs');
  hasIgnoresFile = true;
} catch {
  // eslint.ignores.cjs doesn't exist
}

if (hasIgnoresFile) {
  const ignores = require('./eslint.ignores.cjs');
  customConfig = [{ignores}];
} else {
  try {
    require.resolve('./eslint.ignores.js');
    const ignores = require('./eslint.ignores.js');
    customConfig = [{ignores}];
  } catch {
    // eslint.ignores.js doesn't exist
  }
}

module.exports = [
  ...customConfig,
  ...require('gts'),
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.json'],
      },
    },
  },
];

.eslintignore から eslint.ignores.js への移行

.eslintignore を削除し、以下の内容で eslint.ignores.js を作成する。必要に応じて内容を変更する。

module.exports = [
  '**/node_modules/**',
  '**/.angular/**',
  '**/dist/**',
  '**/coverage/**',
  '**/out-tsc/**',
  '**/tmp/**',
  '**/build/**',
  '**/*.log',
  '**/template/**',
  '**/template-ui/**',
];

.prettierrc.json から .prettierrc.js への移行

.prettierrc.json を削除し、以下の内容で .prettierrc.js を作成する。必要に応じて内容を変更する。

gts の .prettierrc.json を参照するようになっている。

module.exports = {
  ...require('gts/.prettierrc.json'),
  overrides: [
    {
      files: '*.html',
      options: {
        parser: 'angular',
        printWidth: 100,
      },
    },
  ],
};

パッケージのアップデート、package.json の更新

メジャーアップデートが行われ、かつ、動作影響が大きい以下のパッケージをアップデートする。

npm install eslint@10.5.0 gts@7.0.0 @typescript-eslint/eslint-plugin@8.61.1

その後

npm run lint && npm run test && npm run build

を実行し、エラーがないことを確認する。

試験した環境では、linter の癖が変わったため、ソースコードに差分が発生したので、その差分をコミットした。

{} 内のスペースが削除されている。

その他、必要に応じて、clasp, @types/google-apps-script, typescript, jest, ts-jest, rollup-plugin-typescript2, eslint-… などのパッケージもアップデートする。

試験した環境では以下のようにしつつ、npm run lint && npm run test && npm run build を実行し、エラーがないことを確認した。

npm update typescript
npm update clasp @types/google-apps-script
npm update jest ts-jest
npm update rollup-plugin-typescript2

メモ

npx @google/aside init

✔ Generate package.json? … No / Yes
✔ Adding scripts...
✔ Saving package.json...
✔ Installing dependencies...
✔ Installing src template...
✔ Installing test template...
✔ Script ID (optional): … 
✔ Script ID for production environment (optional): … 
✔ Creating aside_v1.5.0_test...

-> Google Sheets Link: https://drive.google.com/open?id=...
-> Apps Script Link: https://script.google.com/d/.../edit

npm notice
npm notice New minor version of npm available! 11.12.1 -> 11.17.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.17.0
npm notice To update run: npm install -g npm@11.17.0
npm notice

# エラーなし
npm run deploy

ls するとルートレベルのファイルは以下である。

LICENSE
appsscript.json
dist
eslint.config.js
eslint.ignores.js
jest.config.json
license-config.json
license-header.txt
node_modules
package-lock.json
package.json
rollup.config.mjs
src
test
tsconfig.json

ASIDE v1.5.0 Migration Guide

Overview

Versions of ASIDE prior to v1.5.0 had the following issues:

  • The ESLint config was in the .eslintrc.json format.
    • ESLint has recommended the Flat Config format since v9, but it was not supported.
    • It was locked to ESLint v8.57.1.
  • Compatibility with gts was broken.
    • From version gts 7.0.0, ESLint 9.37.0 has been adopted, but due to the reason above, running the lint command fails.

Since ASIDE v1.5.0 now provides eslint.config.js, there are no issues when creating a new project.
This guide outlines the actual steps to take when upgrading an existing project from v1.4.6 or below (under v1.5.0) to v1.5.0 or above.

Preparing Files

Updating tsconfig.json

Changes:

  • Changed "moduleResolution": "node" to "moduleResolution": "bundler".
  • "dom" was added, resulting in "lib": ["es2020", "dom"].
  • "types": ["jest", "node", "google-apps-script"] was added.
--- tsconfig.json       2025-07-26 18:54:37.959618437 +0900
+++ ../aside_v1.5.0_test/tsconfig.json  2026-06-20 12:57:13.365750560 +0900
@@ -2,8 +2,8 @@
   "compilerOptions": {
     "target": "es2020",
     "module": "es2020",
-    "lib": ["es2020"],
-    "moduleResolution": "node",
+    "lib": ["es2020", "dom"],
+    "moduleResolution": "bundler",
     "outDir": "dist",
     "rootDir": ".",
     "strict": true,
@@ -12,7 +12,8 @@
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
     "allowUnreachableCode": false,
-    "allowUnusedLabels": false
+    "allowUnusedLabels": false,
+    "types": ["jest", "node", "google-apps-script"]
   },
   "include": ["src/**/*", "test/**/*", "rollup.config.mjs"]
 }

Migrating from .eslintrc.json to eslint.config.js

Delete .eslintrc.json and create eslint.config.js with the following content. Modify the content as necessary.

The original .eslintrc.json had a structure like:

{
  "env": {
    "browser": true,
    "node": true,
    "es2020": true
  },
  "extends": ["./node_modules/gts", "prettier"],
  "overrides": [],
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "project": "./tsconfig.json"
  },
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  },
  "ignorePatterns": ["template/**/*", "template-ui/**/*"]
}

Key changes:

  • env and plugins sections are removed.
  • project remains the same.
  • gts is required instead of referenced in extends.
  • ignorePatterns is moved to eslint.ignores.js (explained below).
let customConfig = [];
let hasIgnoresFile = false;
try {
  require.resolve('./eslint.ignores.cjs');
  hasIgnoresFile = true;
} catch {
  // eslint.ignores.cjs doesn't exist
}

if (hasIgnoresFile) {
  const ignores = require('./eslint.ignores.cjs');
  customConfig = [{ignores}];
} else {
  try {
    require.resolve('./eslint.ignores.js');
    const ignores = require('./eslint.ignores.js');
    customConfig = [{ignores}];
  } catch {
    // eslint.ignores.js doesn't exist
  }
}

module.exports = [
  ...customConfig,
  ...require('gts'),
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.json'],
      },
    },
  },
];

Migrating from .eslintignore to eslint.ignores.js

Delete .eslintignore and create eslint.ignores.js with the following content. Modify the content as necessary.

module.exports = [
  '**/node_modules/**',
  '**/.angular/**',
  '**/dist/**',
  '**/coverage/**',
  '**/out-tsc/**',
  '**/tmp/**',
  '**/build/**',
  '**/*.log',
  '**/template/**',
  '**/template-ui/**',
];

Migrating from .prettierrc.json to .prettierrc.js

Delete .prettierrc.json and create .prettierrc.js with the following content. Modify the content as necessary.

It is configured to extend the .prettierrc.json from the gts package.

module.exports = {
  ...require('gts/.prettierrc.json'),
  overrides: [
    {
      files: '*.html',
      options: {
        parser: 'angular',
        printWidth: 100,
      },
    },
  ],
};

Package Updates and Updating package.json

Install and update the following key packages, which undergo major version upgrades and have a significant impact on behavior:

npm install eslint@10.5.0 gts@7.0.0 @typescript-eslint/eslint-plugin@8.61.1

Afterward, run the following commands and confirm there are no errors:

npm run lint && npm run test && npm run build

In the environment we tested, differences occurred in the source code due to changes in linter formatting rules (e.g., spaces inside {} were removed), so we committed those changes.

As necessary, update other packages such as clasp, @types/google-apps-script, typescript, jest, ts-jest, rollup-plugin-typescript2, eslint-..., etc.

In our test environment, we updated the packages with the following commands while ensuring that npm run lint && npm run test && npm run build completed successfully without any errors:

npm update typescript
npm update clasp @types/google-apps-script
npm update jest ts-jest
npm update rollup-plugin-typescript2

Notes

npx @google/aside init

✔ Generate package.json? … No / Yes
✔ Adding scripts...
✔ Saving package.json...
✔ Installing dependencies...
✔ Installing src template...
✔ Installing test template...
✔ Script ID (optional): … 
✔ Script ID for production environment (optional): … 
✔ Creating aside_v1.5.0_test...

-> Google Sheets Link: https://drive.google.com/open?id=...
-> Apps Script Link: https://script.google.com/d/.../edit

npm notice
npm notice New minor version of npm available! 11.12.1 -> 11.17.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.17.0
npm notice To update run: npm install -g npm@11.17.0
npm notice

# No errors
npm run deploy

Running ls reveals the following files at the root level:

LICENSE
appsscript.json
dist
eslint.config.js
eslint.ignores.js
jest.config.json
license-config.json
license-header.txt
node_modules
package-lock.json
package.json
rollup.config.mjs
src
test
tsconfig.json

misc

Posted by tako