How to generate next-env.d.ts in a CI job that requires it?

[melanieseltzer]

Summary

I've run into a situation recently that has me scratching my head on the best way to handle, so I'm hoping the community could provide some insight on best practice 😄

So, I have a CI pipeline setup with GitHub Actions that does a couple of sanity checks in separate jobs:

jobs:
  formatting:
    name: Prettier
    .... runs yarn format:check
  lint:
    name: ESLint
    .... runs yarn lint
  typecheck:
    name: Typecheck
    .... runs yarn typecheck

I recently created a PR and statically imported an image, like this:

import Avatar from '../../public/images/avatar.jpg'

As soon as I pushed my commit, CI failed on the lint and typecheck jobs with these errors:

I quickly realized it's because the next-env.d.ts file is only generated on next dev or next build, and I have it gitignored, so the file doesn't exist in CI (because those jobs don't require a build before running, so I'm not doing it).

I did some research and saw that recently there's been some similar issues filed about this:

#46104
#46360

They seem to mostly be related to linting, and recently there's been a PR that's landed that generates next-env.d.ts file during next lint command, which is nice 🎉

However, it's still not clear to me what I should be doing for other jobs that require the next-env.d.ts, like my typechecking job. From what I can tell, there's a couple ways to handle it:

• Commit the next-env.d.ts into source control, despite it not being recommended to do so. I'd prefer not to do this, but maybe it's recommended in this situation?

A file named next-env.d.ts will be created at the root of your project. This file ensures Next.js types are picked up by the TypeScript compiler. You should not remove it or edit it as it can change at any time. This file should not be committed and should be ignored by version control (e.g. inside your .gitignore file).

• Consolidate all jobs into one job, and have next lint run first, so that next-env.d.ts is available for any other scripts that come after. I like having my jobs separate so this doesn't seem like a nice choice, but maybe others find it acceptable.

• Add a next build into the typecheck job to generate the file first. It would bloat up my CI run time 😕

• Move the lint job to be first, then use upload-artifact to copy the next-env.d.ts file and make it available between jobs. This seems like the best solution currently?

Curious what other people are doing here!

Additional information

No response

Example

No response

[yuki-yamamura]

@melanieseltzer
Thanks for your insights. It's very helpful for me. I have the same issue and would like to know how other people deal with it.
Here is my workflow file:

# run every check on the same runner
jobs:
  main:
    - name: install dependencies
      run: npm ci
    - name: run Prettier
      run: npm run format
    - name: run ESLint and Stylelint
      run: npm run lint
    - name: run Jest
      run: npm run test:ci
    - name: run TypeScript Compiler
      run: npm run type

and package.json.

  "scripts": {
    "format": "prettier --write --log-level=warn 'src/**/*.{js,jsx,ts,tsx,css,scss,json}'",
    "lint:es": "eslint --fix 'src/**/*.{js,jsx,ts,tsx}'",
    "lint:style": "stylelint --fix 'src/**/*.{css,scss}'",
    "lint": "npm run -s lint:es; npm run -s lint:style",
    "test:ci": "jest --ci --silent --passWithNoTests",
    "type": "bash -c tsc --noEmit",
    "postinstall": "next build"
  },

After some research, I decided to run next build on ci and use .next/cache as well as possible to speed up the build time. I don't know whether this workaround is correct or not, but it works for me.

Steps:

1. Add postinstall script to package.json to run the build command before installing dependencies.
2. Add the cache action to a workflow file.

     "lint": "npm run -s lint:es; npm run -s lint:style",
     "test:ci": "jest --ci --silent --passWithNoTests",
     "type": "bash -c tsc --noEmit",
+    "postinstall": "next build"
   },

 jobs:
   main:
+  - uses: actions/cache@v3
+    with:
+      path: |
+        ~/.npm
+        ${{ github.workspace }}/.next/cache
+      key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
+      restore-keys: |
+        ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
     - name: install dependencies
       run: npm ci
     - name: run Prettier
     - name: run Jest
       run: npm run test:ci
     - name: run TypeScript Compiler
       run: npm run type

References:

• [NEXT-671] Next.js 13.2.1 - Module '"next/navigation"' has no exported member 'usePathname'. #46360 (comment)
• https://nextjs.org/docs/pages/building-your-application/deploying/ci-build-caching#github-actions

[TzviPM]

In my particular case, I have a lightweight CI step that includes type checking, but another pipeline runs the full build. My issue was typed links specifically, and I just included the .next/types/link.d.ts file in the git history.

[danielpadmore]

We've just ran into this issue and solved it by adding the needed types to tsconfig.json. For us, we could create a dedicated tsconfig, which extended the main one just for static type checks in CI.

For example, if you need next global and image types, add the following to your compilerOptions:

{
  "compilerOptions": {
    "types": ["next", "next/types/global", "next/image-types/global"]
  }
}

The end result is that nextjs knows no different, and you point tsc to your dedicated tsconfig for static type checks without needing to run next build

tsc -p /path/to/config.json