happy-css-modules 0.4.0 → 0.6.0

package/src/{loader → locator}/postcss.ts

@@ -11,14 +11,20 @@ export type Position = {
   column: number;
 };
 
-/** The location of class selector. */
-export type Location = {
-  filePath: string;
-  /** The inclusive starting position of the node's source (compatible with postcss). */
-  start: Position;
-  /** The inclusive ending position of the node's source (compatible with postcss). */
-  end: Position;
-};
+/** The original location of class selector. If the original location is not found, all fields are `undefined`. */
+export type Location =
+  | {
+      filePath: string;
+      /** The inclusive starting position of the node's source (compatible with postcss). */
+      start: Position;
+      /** The inclusive ending position of the node's source (compatible with postcss). */
+      end: Position;
+    }
+  | {
+      filePath: undefined;
+      start: undefined;
+      end: undefined;
+    };
 
 function removeDependenciesPlugin(): Plugin {
   return {
@@ -80,49 +86,45 @@ export function getOriginalLocation(rule: Rule, classSelector: ClassName): Locat
   if (rule.source.end === undefined || classSelector.source.end === undefined) throw new Error('Node#end is undefined');
   if (rule.source.input.file === undefined) throw new Error('Node#input.file is undefined');
 
-  const start = {
+  const classSelectorStartPosition = {
     // The line is 1-based.
     line: rule.source.start.line + (classSelector.source.start.line - 1),
     // The column is 1-based.
     column: rule.source.start.column + (classSelector.source.start.column - 1),
   };
-  const end = {
-    line: start.line,
+  const classSelectorEndPosition = {
+    line: classSelectorStartPosition.line,
     // The column is inclusive.
-    column: start.column + classSelector.value.length,
+    column: classSelectorStartPosition.column + classSelector.value.length,
   };
-  let location = {
+  const classSelectorLocation = {
     filePath: rule.source.input.file,
-    start,
-    end,
+    start: classSelectorStartPosition,
+    end: classSelectorEndPosition,
   };
 
-  if (rule.source.input.map) {
-    const origin = rule.source.input.origin(
-      location.start.line,
-      // The column of `Input#origin` is 0-based. This behavior is undocumented and probably a postcss's bug.
-      // TODO: Open PR to postcss/postcss
-      location.start.column - 1,
-    );
-    if (origin === false) throw new Error('`Input#origin` returned false');
-    if (origin.file === undefined) throw new Error('`FilePosition#file` is undefined');
-
-    location = {
-      filePath: origin.file,
-      start: {
-        line: origin.line,
-        // The column of `Input#origin` is 0-based.
-        column: origin.column + 1,
-      },
-      end: {
-        line: origin.line,
-        // The column of `Input#origin` is 0-based. Also, the column of happy-css-modules is inclusive.
-        column: origin.column + 1 + (classSelector.value.length - 1),
-      },
-    };
-  }
+  if (!rule.source.input.map) return classSelectorLocation;
 
-  return location;
+  const classSelectorOrigin = rule.source.input.origin(
+    classSelectorLocation.start.line,
+    // The column of `Input#origin` is 0-based. This behavior is undocumented and probably a postcss's bug.
+    // TODO: Open PR to postcss/postcss
+    classSelectorLocation.start.column - 1,
+  );
+  if (classSelectorOrigin === false || classSelectorOrigin.file === undefined) {
+    return { filePath: undefined, start: undefined, end: undefined };
+  }
+  return {
+    filePath: classSelectorOrigin.file,
+    start: {
+      line: classSelectorOrigin.line,
+      column: classSelectorOrigin.column + 1,
+    },
+    end: {
+      line: classSelectorOrigin.line,
+      column: classSelectorOrigin.column + classSelector.value.length + 1,
+    },
+  };
 }
 
 function isAtRuleNode(node: Node): node is AtRule {

package/src/resolver/webpack-resolver.test.ts

@@ -2,7 +2,13 @@ import { createFixtures, getFixturePath } from '../test/util.js';
 import { createWebpackResolver } from './webpack-resolver.js';
 
 test('resolves specifier with css-loader mechanism', async () => {
-  const webpackResolver = createWebpackResolver();
+  const webpackResolver = createWebpackResolver({
+    cwd: getFixturePath('/'),
+    webpackResolveAlias: {
+      '@relative': 'test/alias-relative',
+      '@absolute': getFixturePath('/test/alias-absolute'),
+    },
+  });
   const request = getFixturePath('/test/1.css');
   createFixtures({
     '/node_modules/package-1/index.css': `.a {}`,
@@ -12,6 +18,8 @@ test('resolves specifier with css-loader mechanism', async () => {
     '/node_modules/package-4/style.css': `.a {}`,
     '/node_modules/@scoped/package-5/index.css': `.a {}`,
     '/node_modules/package-6/index.css': `.a {}`,
+    '/test/alias-relative/alias.css': `.a {}`,
+    '/test/alias-absolute/alias.css': `.a {}`,
   });
   expect(await webpackResolver('~package-1/index.css', { request })).toBe(
     getFixturePath('/node_modules/package-1/index.css'),
@@ -25,22 +33,43 @@ test('resolves specifier with css-loader mechanism', async () => {
   expect(await webpackResolver('package-6/index.css', { request })).toBe(
     getFixturePath('/node_modules/package-6/index.css'),
   );
+  expect(await webpackResolver('@relative/alias.css', { request })).toBe(
+    getFixturePath('/test/alias-relative/alias.css'),
+  );
+  expect(await webpackResolver('@absolute/alias.css', { request })).toBe(
+    getFixturePath('/test/alias-absolute/alias.css'),
+  );
 });
 
 test('resolves specifier with sass-loader mechanism', async () => {
-  const webpackResolver = createWebpackResolver({ sassLoadPaths: [getFixturePath('/test/styles')] });
+  const webpackResolver = createWebpackResolver({
+    cwd: getFixturePath('/'),
+    sassLoadPaths: ['test/load-paths-relative', getFixturePath('/test/load-paths-absolute')],
+    webpackResolveAlias: {
+      '@relative': 'test/alias-relative',
+      '@absolute': getFixturePath('/test/alias-absolute'),
+    },
+  });
   const request = getFixturePath('/test/1.scss');
   createFixtures({
     '/node_modules/package-1/index.scss': `.a {}`,
-    '/test/styles/load-paths.scss': `.a {}`,
+    '/test/load-paths-relative/load-paths-relative.scss': `.a {}`,
+    '/test/load-paths-absolute/load-paths-absolute.scss': `.a {}`,
     '/test/_partial-import.scss': `.a {}`,
+    '/test/alias-relative/alias.scss': `.a {}`,
+    '/test/alias-absolute/alias.scss': `.a {}`,
   });
   expect(await webpackResolver('~package-1/index.scss', { request })).toBe(
     getFixturePath('/node_modules/package-1/index.scss'),
   );
   expect(await webpackResolver('~package-1', { request })).toBe(getFixturePath('/node_modules/package-1/index.scss'));
   // ref: https://github.com/webpack-contrib/sass-loader/blob/bed9fb5799a90020d43f705ea405f85b368621d7/test/scss/import-include-paths.scss#L1
-  expect(await webpackResolver('load-paths', { request })).toBe(getFixturePath('/test/styles/load-paths.scss'));
+  expect(await webpackResolver('load-paths-relative', { request })).toBe(
+    getFixturePath('/test/load-paths-relative/load-paths-relative.scss'),
+  );
+  expect(await webpackResolver('load-paths-absolute', { request })).toBe(
+    getFixturePath('/test/load-paths-absolute/load-paths-absolute.scss'),
+  );
   // https://sass-lang.com/documentation/at-rules/import#partials
   // https://github.com/webpack-contrib/sass-loader/blob/0e9494074f69a6b6d47efea6c083a02a31a5ae84/test/sass/import-with-underscore.sass
   expect(await webpackResolver('partial-import', { request: getFixturePath('/test/1.scss') })).toBe(
@@ -49,14 +78,30 @@ test('resolves specifier with sass-loader mechanism', async () => {
   expect(await webpackResolver('test/partial-import', { request: getFixturePath('/test') })).toBe(
     getFixturePath('/test/_partial-import.scss'),
   );
+  expect(await webpackResolver('@relative/alias.scss', { request })).toBe(
+    getFixturePath('/test/alias-relative/alias.scss'),
+  );
+  expect(await webpackResolver('@absolute/alias.scss', { request })).toBe(
+    getFixturePath('/test/alias-absolute/alias.scss'),
+  );
 });
 
 test('resolves specifier with less-loader mechanism', async () => {
-  const webpackResolver = createWebpackResolver({ lessIncludePaths: [getFixturePath('/test/styles')] });
+  const webpackResolver = createWebpackResolver({
+    cwd: getFixturePath('/'),
+    lessIncludePaths: ['test/include-paths-relative', getFixturePath('/test/include-paths-absolute')],
+    webpackResolveAlias: {
+      '@relative': 'test/alias-relative',
+      '@absolute': getFixturePath('/test/alias-absolute'),
+    },
+  });
   const request = getFixturePath('/test/1.less');
   createFixtures({
     '/node_modules/package-1/index.less': `.a {}`,
-    '/test/styles/include-paths.less': `.a {}`,
+    '/test/include-paths-relative/include-paths-relative.less': `.a {}`,
+    '/test/include-paths-absolute/include-paths-absolute.less': `.a {}`,
+    '/test/alias-relative/alias.less': `.a {}`,
+    '/test/alias-absolute/alias.less': `.a {}`,
   });
   expect(await webpackResolver('~package-1/index.less', { request })).toBe(
     getFixturePath('/node_modules/package-1/index.less'),
@@ -65,5 +110,16 @@ test('resolves specifier with less-loader mechanism', async () => {
   // ref: https://github.com/webpack-contrib/less-loader/blob/81a0d27eb6d18e5dc550a60fc1007fdc77305b78/test/loader.test.js#L248-L253
   // ref: https://github.com/webpack-contrib/less-loader/blob/393147064672ace986ec84aca21f69f0ab819a9c/test/fixtures/import-paths.less#L1
   // ref: https://github.com/webpack-contrib/less-loader/blob/99d80bd290dae50375db6e17c5f56ec33754e258/test/helpers/getCodeFromLess.js#L47-L54
-  expect(await webpackResolver('include-paths', { request })).toBe(getFixturePath('/test/styles/include-paths.less'));
+  expect(await webpackResolver('include-paths-relative', { request })).toBe(
+    getFixturePath('/test/include-paths-relative/include-paths-relative.less'),
+  );
+  expect(await webpackResolver('include-paths-absolute', { request })).toBe(
+    getFixturePath('/test/include-paths-absolute/include-paths-absolute.less'),
+  );
+  expect(await webpackResolver('@relative/alias.less', { request })).toBe(
+    getFixturePath('/test/alias-relative/alias.less'),
+  );
+  expect(await webpackResolver('@absolute/alias.less', { request })).toBe(
+    getFixturePath('/test/alias-absolute/alias.less'),
+  );
 });

package/src/resolver/webpack-resolver.ts

@@ -1,25 +1,43 @@
-import { basename, dirname, join } from 'path';
+import { basename, dirname, join, resolve } from 'path';
 import enhancedResolve from 'enhanced-resolve';
 import { exists } from '../util.js';
 import type { Resolver } from './index.js';
 
 export type WebpackResolverOptions = {
+  /** Working directory path. */
+  cwd?: string | undefined;
   /**
-   * The option compatible with sass's `--load-path`. It is an array of absolute paths.
+   * The option compatible with sass's `--load-path`. It is an array of relative or absolute paths.
+   * @example ['src/styles']
    * @example ['/home/user/repository/src/styles']
    */
   sassLoadPaths?: string[] | undefined;
   /**
-   * The option compatible with less's `--include-path`. It is an array of absolute paths.
+   * The option compatible with less's `--include-path`. It is an array of relative or absolute paths.
+   * @example ['src/styles']
    * @example ['/home/user/repository/src/styles']
    */
   lessIncludePaths?: string[] | undefined;
+  /**
+   * The option compatible with webpack's `resolve.alias`. It is an object consisting of a pair of alias names and relative or absolute paths.
+   * @example { style: 'src/styles', '@': 'src' }
+   * @example { style: '/home/user/repository/src/styles', '@': '/home/user/repository/src' }
+   */
+  webpackResolveAlias?: Record<string, string> | undefined;
 };
 
 // TODO: Support `resolve.alias` for Node.js API
 export const createWebpackResolver: (webpackResolverOptions?: WebpackResolverOptions | undefined) => Resolver = (
   webpackResolverOptions,
 ) => {
+  const cwd = webpackResolverOptions?.cwd ?? process.cwd();
+  const sassLoadPaths = webpackResolverOptions?.sassLoadPaths?.map((path) => resolve(cwd, path));
+  const lessIncludePaths = webpackResolverOptions?.lessIncludePaths?.map((path) => resolve(cwd, path));
+  const webpackResolveAlias = webpackResolverOptions?.webpackResolveAlias
+    ? Object.fromEntries(
+        Object.entries(webpackResolverOptions?.webpackResolveAlias).map(([key, value]) => [key, resolve(cwd, value)]),
+      )
+    : undefined;
   /**
    * A resolver compatible with css-loader.
    *
@@ -33,6 +51,7 @@ export const createWebpackResolver: (webpackResolverOptions?: WebpackResolverOpt
     mainFiles: ['index', '...'],
     extensions: ['.css', '...'],
     preferRelative: true,
+    alias: webpackResolveAlias,
   });
 
   /**
@@ -48,7 +67,8 @@ export const createWebpackResolver: (webpackResolverOptions?: WebpackResolverOpt
     extensions: ['.sass', '.scss', '.css'],
     restrictions: [/\.((sa|sc|c)ss)$/i],
     preferRelative: true,
-    modules: ['node_modules', ...(webpackResolverOptions?.sassLoadPaths ?? [])],
+    alias: webpackResolveAlias,
+    modules: ['node_modules', ...(sassLoadPaths ?? [])],
   });
 
   /**
@@ -63,7 +83,8 @@ export const createWebpackResolver: (webpackResolverOptions?: WebpackResolverOpt
     mainFiles: ['index', '...'],
     extensions: ['.less', '.css'],
     preferRelative: true,
-    modules: ['node_modules', ...(webpackResolverOptions?.lessIncludePaths ?? [])],
+    alias: webpackResolveAlias,
+    modules: ['node_modules', ...(lessIncludePaths ?? [])],
   });
 
   // NOTE: In theory, `sassLoaderResolver` should only be used when the resolver is called from `sassTransformer`.

package/src/runner.test.ts

@@ -1,12 +1,26 @@
-import { readFile, writeFile } from 'fs/promises';
+import { readFile, rm, writeFile } from 'fs/promises';
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import * as fileCacheNpm from '@file-cache/npm';
 import { jest } from '@jest/globals';
 import chalk from 'chalk';
 import dedent from 'dedent';
-import AggregateError from 'es-aggregate-error';
 import type { Watcher } from './runner.js';
-import { run } from './runner.js';
 import { createFixtures, exists, getFixturePath, waitForAsyncTask } from './test/util.js';
 
+const require = createRequire(import.meta.url);
+
+jest.unstable_mockModule('@file-cache/npm', () => ({
+  ...fileCacheNpm, // Inherit native functions
+  createNpmPackageKey: () => 'mocked-key',
+}));
+
+const { run } = await import('./runner.js');
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
 // eslint-disable-next-line @typescript-eslint/no-empty-function
 const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
 
@@ -15,8 +29,17 @@ const defaultOptions = {
   declarationMap: true,
   silent: true,
   cwd: getFixturePath('/'),
+  cache: false,
 };
 
+const dir = join(dirname(fileURLToPath(import.meta.url)));
+
+beforeEach(async () => {
+  consoleLogSpy.mockClear();
+  consoleErrorSpy.mockClear();
+  await rm(resolve(dir, '../node_modules/.cache/happy-css-modules'), { recursive: true, force: true }); // clear cache
+});
+
 // Exit the watcher even if the test fails
 let watcher: Watcher | undefined;
 afterEach(async () => {
@@ -37,6 +60,49 @@ test('generates .d.ts and .d.ts.map', async () => {
   expect(await readFile(getFixturePath('/test/2.css.d.ts.map'), 'utf8')).toMatchSnapshot();
 });
 
+test('uses cache', async () => {
+  createFixtures({
+    '/test/1.css': '.a {}',
+  });
+  await run({ ...defaultOptions, declarationMap: true, silent: false, cache: true });
+  expect(consoleLogSpy).toBeCalledTimes(1);
+  expect(consoleLogSpy).toHaveBeenNthCalledWith(1, expect.stringContaining('generated'));
+  consoleLogSpy.mockClear();
+
+  // Skip generation
+  await run({ ...defaultOptions, declarationMap: true, silent: false, cache: true });
+  expect(consoleLogSpy).toBeCalledTimes(1);
+  expect(consoleLogSpy).toHaveBeenNthCalledWith(1, expect.stringContaining('skipped'));
+  consoleLogSpy.mockClear();
+
+  // Generates if generated files are missing
+  await rm(getFixturePath('/test/1.css.d.ts'));
+  await run({ ...defaultOptions, declarationMap: true, silent: false, cache: true });
+  expect(consoleLogSpy).toBeCalledTimes(1);
+  expect(consoleLogSpy).toHaveBeenNthCalledWith(1, expect.stringContaining('generated'));
+  consoleLogSpy.mockClear();
+
+  // Generates if options are changed
+  await run({ ...defaultOptions, declarationMap: false, silent: false, cache: true });
+  expect(consoleLogSpy).toBeCalledTimes(1);
+  expect(consoleLogSpy).toHaveBeenNthCalledWith(1, expect.stringContaining('generated'));
+  consoleLogSpy.mockClear();
+});
+
+test('outputs logs', async () => {
+  createFixtures({
+    '/test/1.css': '.a {}',
+  });
+  await run({ ...defaultOptions, silent: false, cache: true });
+  expect(consoleLogSpy).toBeCalledTimes(1);
+  expect(consoleLogSpy).toHaveBeenNthCalledWith(1, `${chalk.green('test/1.css')} (generated)`);
+  consoleLogSpy.mockClear();
+
+  await run({ ...defaultOptions, silent: false, cache: true });
+  expect(consoleLogSpy).toBeCalledTimes(1);
+  expect(consoleLogSpy).toHaveBeenNthCalledWith(1, `${chalk.gray('test/1.css (skipped)')}`);
+});
+
 test.todo('changes dts format with localsConvention options');
 test('does not emit declaration map if declarationMap is false', async () => {
   createFixtures({
@@ -87,9 +153,9 @@ test('returns an error if the file fails to process in non-watch mode', async ()
   // The error is logged to console.error.
   expect(consoleErrorSpy).toHaveBeenCalledTimes(2);
   // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
-  expect(consoleErrorSpy).toHaveBeenNthCalledWith(1, chalk.red('[Error] ' + error.errors[0]));
+  expect(consoleErrorSpy).toHaveBeenNthCalledWith(1, chalk.red('[Error] ' + error.errors[0]!.stack));
   // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
-  expect(consoleErrorSpy).toHaveBeenNthCalledWith(2, chalk.red('[Error] ' + error.errors[1]));
+  expect(consoleErrorSpy).toHaveBeenNthCalledWith(2, chalk.red('[Error] ' + error.errors[1].stack));
 
   // The valid files are emitted.
   expect(await exists(getFixturePath('/test/1.css.d.ts'))).toBe(true);
@@ -129,27 +195,53 @@ describe('handles external files', () => {
 });
 
 test('sassLoadPaths', async () => {
-  const sassLoadPaths = ['test/relative', getFixturePath('/test/absolute')];
+  const sassLoadPaths = ['test/relative'];
   createFixtures({
     '/test/1.scss': dedent`
     @import '2.scss';
-    @import '3.scss';
     `,
     '/test/relative/2.scss': `.a { dummy: ''; }`,
-    '/test/absolute/3.scss': `.b { dummy: ''; }`,
   });
   await run({ ...defaultOptions, sassLoadPaths }); // not throw
 });
 
 test('lessIncludePaths', async () => {
-  const lessIncludePaths = ['test/relative', getFixturePath('/test/absolute')];
+  const lessIncludePaths = ['test/relative'];
   createFixtures({
     '/test/1.less': dedent`
     @import '2.less';
-    @import '3.less';
     `,
     '/test/relative/2.less': `.a { dummy: ''; }`,
-    '/test/absolute/3.less': `.b { dummy: ''; }`,
   });
   await run({ ...defaultOptions, lessIncludePaths }); // not throw
 });
+
+test('webpackResolveAlias', async () => {
+  const webpackResolveAlias = { '@relative': 'test/relative' };
+  createFixtures({
+    '/test/1.less': dedent`
+    @import '@relative/2.less';
+    `,
+    '/test/relative/2.less': `.a { dummy: ''; }`,
+  });
+  await run({ ...defaultOptions, webpackResolveAlias }); // not throw
+});
+
+test('postcssConfig', async () => {
+  const uuid = randomUUID();
+  const postcssConfig = `${uuid}/postcss.config.js`;
+  createFixtures({
+    [`/${uuid}/postcss.config.js`]: dedent`
+    module.exports = {
+      plugins: [
+        require('${require.resolve('postcss-simple-vars')}'),
+      ],
+    };
+    `,
+    '/test/1.css': dedent`
+    $prefix: foo;
+    .$(prefix)_bar {}
+    `,
+  });
+  await run({ ...defaultOptions, postcssConfig }); // not throw
+});

package/src/runner.ts

@@ -1,16 +1,17 @@
-import { resolve } from 'path';
+import { resolve, relative } from 'path';
 import * as process from 'process';
 import * as util from 'util';
+import { createCache } from '@file-cache/core';
+import { createNpmPackageKey } from '@file-cache/npm';
 import chalk from 'chalk';
 import * as chokidar from 'chokidar';
-import AggregateError from 'es-aggregate-error';
 import _glob from 'glob';
-import { emitGeneratedFiles } from './emitter/index.js';
-import { Loader } from './loader/index.js';
+import { isGeneratedFilesExist, emitGeneratedFiles } from './emitter/index.js';
+import { Locator } from './locator/index.js';
 import type { Resolver } from './resolver/index.js';
 import { createDefaultResolver } from './resolver/index.js';
-import { type Transformer } from './transformer/index.js';
-import { isMatchByGlob } from './util.js';
+import { createDefaultTransformer, type Transformer } from './transformer/index.js';
+import { getInstalledPeerDependencies, isMatchByGlob } from './util.js';
 
 const glob = util.promisify(_glob);
 
@@ -22,7 +23,6 @@ export type LocalsConvention = 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashe
 
 export interface RunnerOptions {
   pattern: string;
-  outDir?: string | undefined;
   watch?: boolean | undefined;
   localsConvention?: LocalsConvention | undefined;
   declarationMap?: boolean | undefined;
@@ -40,6 +40,29 @@ export interface RunnerOptions {
    * @example ['/home/user/repository/src/styles']
    */
   lessIncludePaths?: string[] | undefined;
+  /**
+   * The option compatible with webpack's `resolve.alias`. It is an object consisting of a pair of alias names and relative or absolute paths.
+   * @example { style: 'src/styles', '@': 'src' }
+   * @example { style: '/home/user/repository/src/styles', '@': '/home/user/repository/src' }
+   */
+  webpackResolveAlias?: Record<string, string> | undefined;
+  /**
+   * The option compatible with postcss's `--config`. It is a relative or absolute path.
+   * @example '.'
+   * @example 'postcss.config.js'
+   * @example '/home/user/repository/src'
+   */
+  postcssConfig?: string | undefined;
+  /**
+   * Only generate .d.ts and .d.ts.map for changed files.
+   * @default true
+   */
+  cache?: boolean | undefined;
+  /**
+   * Strategy for the cache to use for detecting changed files.
+   * @default 'content'
+   */
+  cacheStrategy?: 'content' | 'metadata' | undefined;
   /**
    * Silent output. Do not show "files written" messages.
    * @default false
@@ -61,43 +84,64 @@ export async function run(options: RunnerOptions): Promise<void>;
 export async function run(options: RunnerOptions): Promise<Watcher | void> {
   const cwd = options.cwd ?? process.cwd();
   const silent = options.silent ?? false;
-  const sassLoadPaths = options.sassLoadPaths?.map((path) => resolve(cwd, path));
-  const lessIncludePaths = options.lessIncludePaths?.map((path) => resolve(cwd, path));
-  const resolver = options.resolver ?? createDefaultResolver({ sassLoadPaths, lessIncludePaths });
-  const distOptions = options.outDir
-    ? {
-        rootDir: cwd, // TODO: support `--rootDir` option
-        outDir: options.outDir,
-      }
-    : undefined;
+  const resolver =
+    options.resolver ??
+    createDefaultResolver({
+      cwd,
+      sassLoadPaths: options.sassLoadPaths,
+      lessIncludePaths: options.lessIncludePaths,
+      webpackResolveAlias: options.webpackResolveAlias,
+    });
+  const transformer = options.transformer ?? createDefaultTransformer({ cwd, postcssConfig: options.postcssConfig });
 
-  const loader = new Loader({ transformer: options.transformer, resolver });
+  const installedPeerDependencies = await getInstalledPeerDependencies();
+  const cache = await createCache({
+    mode: options.cacheStrategy ?? 'content',
+    keys: [
+      () => createNpmPackageKey(['happy-css-modules', ...installedPeerDependencies]),
+      () => {
+        return JSON.stringify(options);
+      },
+    ],
+    noCache: !(options.cache ?? true),
+  });
+
+  const locator = new Locator({ transformer, resolver });
   const isExternalFile = (filePath: string) => {
     return !isMatchByGlob(filePath, options.pattern, { cwd });
   };
 
   async function processFile(filePath: string) {
     try {
-      const result = await loader.load(filePath);
+      const result = await locator.load(filePath);
       await emitGeneratedFiles({
         filePath,
         tokens: result.tokens,
-        distOptions,
         emitDeclarationMap: options.declarationMap,
         dtsFormatOptions: {
           localsConvention: options.localsConvention,
         },
-        silent,
-        cwd,
         isExternalFile,
       });
+      if (!silent) console.log(`${chalk.green(relative(cwd, filePath))} (generated)`);
     } catch (error) {
-      // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
-      console.error(chalk.red('[Error] ' + error));
+      if (error instanceof Error) {
+        // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+        console.error(chalk.red('[Error] ' + error.stack));
+      } else {
+        // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+        console.error(chalk.red('[Error] ' + error));
+      }
       throw error;
     }
   }
 
+  async function isChangedFile(filePath: string) {
+    const result = await cache.getAndUpdateCache(filePath);
+    if (result.error) throw result.error;
+    return result.changed;
+  }
+
   if (options.watch) {
     if (!silent) console.log('Watch ' + options.pattern + '...');
     const watcher = chokidar.watch([options.pattern.replace(/\\/g, '/')], { cwd });
@@ -114,11 +158,25 @@ export async function run(options: RunnerOptions): Promise<Watcher | void> {
       // convert relative path to absolute path
       .map((file) => resolve(cwd, file));
 
-    // TODO: Use `@file-cache/core` to process only files that have changed
     const errors: unknown[] = [];
     for (const filePath of filePaths) {
-      await processFile(filePath).catch((e: unknown) => errors.push(e));
+      try {
+        const _isGeneratedFilesExist = await isGeneratedFilesExist(filePath, options.declarationMap);
+        const _isChangedFile = await isChangedFile(filePath);
+        // Generate .d.ts and .d.ts.map only when the file has been updated.
+        // However, if .d.ts or .d.ts.map has not yet been generated, always generate.
+        if (!_isGeneratedFilesExist || _isChangedFile) {
+          await processFile(filePath);
+        } else {
+          if (!silent) console.log(chalk.gray(`${relative(cwd, filePath)} (skipped)`));
+        }
+      } catch (e: unknown) {
+        errors.push(e);
+      }
     }
     if (errors.length > 0) throw new AggregateError(errors, 'Failed to process files');
   }
+
+  // Write cache state to file for persistence
+  await cache.reconcile();
 }