feat: Use ~/* import alias (#1191)

* feat: Use @/* import alias

* Allow users override import alias

* Change default import alias to ~/

* Run setImportAliases at a later stage

---------

Co-authored-by: Christopher Ehrlich <[email protected]>

Author: bai

Diff for: .changeset/purple-carpets-cough.md

@@ -0,0 +1,5 @@
+---
+"create-t3-app": patch
+---
+
+Use ~/\* import alias

Diff for: cli/src/cli/index.ts

@@ -13,6 +13,7 @@ interface CliFlags {
   noGit: boolean;
   noInstall: boolean;
   default: boolean;
+  importAlias: string;
 
   /** @internal Used in CI. */
   CI: boolean;
@@ -44,6 +45,7 @@ const defaultOptions: CliResults = {
     trpc: false,
     prisma: false,
     nextAuth: false,
+    importAlias: "~/",
   },
 };
 
@@ -105,6 +107,12 @@ export const runCli = async () => {
       "Experimental: Boolean value if we should install tRPC. Must be used in conjunction with `--CI`.",
       (value) => !!value && value !== "false",
     )
+    /** @experimental - Used for CI E2E tests. Used in conjunction with `--CI` to skip prompting. */
+    .option(
+      "-i, --import-alias",
+      "Explicitly tell the CLI to use a custom import alias",
+      defaultOptions.flags.importAlias,
+    )
     /** END CI-FLAGS */
     .version(getVersion(), "-v, --version", "Display the version number")
     .addHelpText(
@@ -164,6 +172,8 @@ export const runCli = async () => {
       if (!cliResults.flags.noInstall) {
         cliResults.flags.noInstall = !(await promptInstall());
       }
+
+      cliResults.flags.importAlias = await promptImportAlias();
     }
   } catch (err) {
     // If the user is not calling create-t3-app from an interactive terminal, inquirer will throw an error with isTTYError = true
@@ -277,3 +287,17 @@ const promptInstall = async (): Promise<boolean> => {
 
   return install;
 };
+
+const promptImportAlias = async (): Promise<string> => {
+  const { importAlias } = await inquirer.prompt<Pick<CliFlags, "importAlias">>({
+    name: "importAlias",
+    type: "input",
+    message: "What import alias would you like configured?",
+    default: defaultOptions.flags.importAlias,
+    transformer: (input: string) => {
+      return input.trim();
+    },
+  });
+
+  return importAlias;
+};

Diff for: cli/src/helpers/createProject.ts

@@ -9,6 +9,7 @@ interface CreateProjectOptions {
   projectName: string;
   packages: PkgInstallerMap;
   noInstall: boolean;
+  importAlias: string;
 }
 
 export const createProject = async ({

Diff for: cli/src/helpers/setImportAlias.ts

@@ -0,0 +1,33 @@
+import fs from "fs";
+import path from "path";
+
+function replaceTextInFiles(
+  directoryPath: string,
+  search: string,
+  replacement: string,
+): void {
+  const files = fs.readdirSync(directoryPath);
+
+  files.forEach((file) => {
+    const filePath = path.join(directoryPath, file);
+    if (fs.statSync(filePath).isDirectory()) {
+      replaceTextInFiles(filePath, search, replacement);
+    } else {
+      const data = fs.readFileSync(filePath, "utf8");
+      const updatedData = data.replace(new RegExp(search, "g"), replacement);
+      fs.writeFileSync(filePath, updatedData, "utf8");
+    }
+  });
+}
+
+export const setImportAlias = async (
+  projectDir: string,
+  importAlias: string,
+) => {
+  const normalizedImportAlias = importAlias
+    .replace(/\*/g, "") // remove any wildcards (~/* -> ~/)
+    .replace(/[^\/]$/, "$&/"); // ensure trailing slash (@ -> ~/)
+
+  // update import alias in any files if not using the default
+  replaceTextInFiles(projectDir, `~/`, normalizedImportAlias);
+};

Diff for: cli/src/index.ts

@@ -6,6 +6,7 @@ import fs from "fs-extra";
 import { runCli } from "~/cli/index.js";
 import { createProject } from "~/helpers/createProject.js";
 import { initializeGit } from "~/helpers/git.js";
+import { setImportAlias } from "~/helpers/setImportAlias.js";
 import { logNextSteps } from "~/helpers/logNextSteps.js";
 import { buildPkgInstallerMap } from "~/installers/index.js";
 import { logger } from "~/utils/logger.js";
@@ -32,7 +33,7 @@ const main = async () => {
   const {
     appName,
     packages,
-    flags: { noGit, noInstall },
+    flags: { noGit, noInstall, importAlias },
   } = await runCli();
 
   const usePackages = buildPkgInstallerMap(packages);
@@ -43,6 +44,7 @@ const main = async () => {
   const projectDir = await createProject({
     projectName: appDir,
     packages: usePackages,
+    importAlias: importAlias,
     noInstall,
   });
 
@@ -56,6 +58,11 @@ const main = async () => {
     spaces: 2,
   });
 
+  // update import alias in any generated files if not using the default
+  if (importAlias !== "~/") {
+    await setImportAlias(projectDir, importAlias);
+  }
+
   if (!noInstall) {
     await installDependencies({ projectDir });
   }

Diff for: cli/template/base/src/pages/_app.tsx

@@ -1,6 +1,6 @@
 import { type AppType } from "next/dist/shared/lib/utils";
 
-import "../styles/globals.css";
+import "~/styles/globals.css";
 
 const MyApp: AppType = ({ Component, pageProps }) => {
   return <Component {...pageProps} />;

Diff for: cli/template/base/tsconfig.json

@@ -15,7 +15,11 @@
     "isolatedModules": true,
     "jsx": "preserve",
     "incremental": true,
-    "noUncheckedIndexedAccess": true
+    "noUncheckedIndexedAccess": true,
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "**/*.cjs", "**/*.mjs"],
   "exclude": ["node_modules"]

Diff for: cli/template/extras/src/pages/_app/with-auth-trpc.tsx

@@ -2,9 +2,9 @@ import { type AppType } from "next/app";
 import { type Session } from "next-auth";
 import { SessionProvider } from "next-auth/react";
 
-import { api } from "../utils/api";
+import { api } from "~/utils/api";
 
-import "../styles/globals.css";
+import "~/styles/globals.css";
 
 const MyApp: AppType<{ session: Session | null }> = ({
   Component,

Diff for: cli/template/extras/src/pages/_app/with-auth.tsx

@@ -2,7 +2,7 @@ import { type AppType } from "next/app";
 import { type Session } from "next-auth";
 import { SessionProvider } from "next-auth/react";
 
-import "../styles/globals.css";
+import "~/styles/globals.css";
 
 const MyApp: AppType<{ session: Session | null }> = ({
   Component,

Diff for: cli/template/extras/src/pages/_app/with-trpc.tsx

@@ -1,8 +1,8 @@
 import { type AppType } from "next/app";
 
-import { api } from "../utils/api";
+import { api } from "~/utils/api";
 
-import "../styles/globals.css";
+import "~/styles/globals.css";
 
 const MyApp: AppType = ({ Component, pageProps }) => {
   return <Component {...pageProps} />;

Diff for: cli/template/extras/src/pages/api/auth/[...nextauth].ts

@@ -1,4 +1,4 @@
 import NextAuth from "next-auth";
-import { authOptions } from "../../../server/auth";
+import { authOptions } from "~/server/auth";
 
 export default NextAuth(authOptions);

Diff for: cli/template/extras/src/pages/api/trpc/[trpc].ts

@@ -1,8 +1,8 @@
 import { createNextApiHandler } from "@trpc/server/adapters/next";
 
-import { env } from "../../../env.mjs";
-import { createTRPCContext } from "../../../server/api/trpc";
-import { appRouter } from "../../../server/api/root";
+import { env } from "~/env.mjs";
+import { createTRPCContext } from "~/server/api/trpc";
+import { appRouter } from "~/server/api/root";
 
 // export API handler
 export default createNextApiHandler({

Diff for: cli/template/extras/src/pages/index/with-auth-trpc-tw.tsx

@@ -3,7 +3,7 @@ import Head from "next/head";
 import Link from "next/link";
 import { signIn, signOut, useSession } from "next-auth/react";
 
-import { api } from "../utils/api";
+import { api } from "~/utils/api";
 
 const Home: NextPage = () => {
   const hello = api.example.hello.useQuery({ text: "from tRPC" });

Diff for: cli/template/extras/src/pages/index/with-auth-trpc.tsx

@@ -4,7 +4,7 @@ import Head from "next/head";
 import Link from "next/link";
 import { signIn, signOut, useSession } from "next-auth/react";
 
-import { api } from "../utils/api";
+import { api } from "~/utils/api";
 
 const Home: NextPage = () => {
   const hello = api.example.hello.useQuery({ text: "from tRPC" });

Diff for: cli/template/extras/src/pages/index/with-trpc-tw.tsx

@@ -2,7 +2,7 @@ import { type NextPage } from "next";
 import Head from "next/head";
 import Link from "next/link";
 
-import { api } from "../utils/api";
+import { api } from "~/utils/api";
 
 const Home: NextPage = () => {
   const hello = api.example.hello.useQuery({ text: "from tRPC" });

Diff for: cli/template/extras/src/pages/index/with-trpc.tsx

@@ -3,7 +3,7 @@ import { type NextPage } from "next";
 import Head from "next/head";
 import Link from "next/link";
 
-import { api } from "../utils/api";
+import { api } from "~/utils/api";
 
 const Home: NextPage = () => {
   const hello = api.example.hello.useQuery({ text: "from tRPC" });

Diff for: cli/template/extras/src/server/api/root.ts

@@ -1,5 +1,5 @@
-import { createTRPCRouter } from "./trpc";
-import { exampleRouter } from "./routers/example";
+import { createTRPCRouter } from "~/server/api/trpc";
+import { exampleRouter } from "~/server/api/routers/example";
 
 /**
  * This is the primary router for your server.

Diff for: cli/template/extras/src/server/api/routers/example/base.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-import { createTRPCRouter, publicProcedure } from "../trpc";
+import { createTRPCRouter, publicProcedure } from "~/server/api/trpc";
 
 export const exampleRouter = createTRPCRouter({
   hello: publicProcedure

Diff for: cli/template/extras/src/server/api/routers/example/with-auth-prisma.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 
-import { createTRPCRouter, publicProcedure, protectedProcedure } from "../trpc";
+import {
+  createTRPCRouter,
+  publicProcedure,
+  protectedProcedure,
+} from "~/server/api/trpc";
 
 export const exampleRouter = createTRPCRouter({
   hello: publicProcedure

Diff for: cli/template/extras/src/server/api/routers/example/with-auth.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 
-import { createTRPCRouter, publicProcedure, protectedProcedure } from "../trpc";
+import {
+  createTRPCRouter,
+  publicProcedure,
+  protectedProcedure,
+} from "~/server/api/trpc";
 
 export const exampleRouter = createTRPCRouter({
   hello: publicProcedure

Diff for: cli/template/extras/src/server/api/routers/example/with-prisma.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-import { createTRPCRouter, publicProcedure } from "../trpc";
+import { createTRPCRouter, publicProcedure } from "~/server/api/trpc";
 
 export const exampleRouter = createTRPCRouter({
   hello: publicProcedure

Diff for: cli/template/extras/src/server/api/trpc/with-auth-prisma.ts

@@ -18,8 +18,8 @@
 import { type CreateNextContextOptions } from "@trpc/server/adapters/next";
 import { type Session } from "next-auth";
 
-import { getServerAuthSession } from "../auth";
-import { prisma } from "../db";
+import { getServerAuthSession } from "~/server/auth";
+import { prisma } from "~/server/db";
 
 type CreateContextOptions = {
   session: Session | null;

Diff for: cli/template/extras/src/server/api/trpc/with-auth.ts

@@ -18,7 +18,7 @@
 import { type CreateNextContextOptions } from "@trpc/server/adapters/next";
 import { type Session } from "next-auth";
 
-import { getServerAuthSession } from "../auth";
+import { getServerAuthSession } from "~/server/auth";
 
 type CreateContextOptions = {
   session: Session | null;

Diff for: cli/template/extras/src/server/api/trpc/with-prisma.ts

@@ -17,7 +17,7 @@
  */
 import { type CreateNextContextOptions } from "@trpc/server/adapters/next";
 
-import { prisma } from "../db";
+import { prisma } from "~/server/db";
 
 type CreateContextOptions = Record<string, never>;
 

Diff for: cli/template/extras/src/server/auth/base.ts

@@ -5,7 +5,7 @@ import {
   type DefaultSession,
 } from "next-auth";
 import DiscordProvider from "next-auth/providers/discord";
-import { env } from "../env.mjs";
+import { env } from "~/env.mjs";
 
 /**
  * Module augmentation for `next-auth` types.

Diff for: cli/template/extras/src/server/auth/with-prisma.ts

@@ -6,8 +6,8 @@ import {
 } from "next-auth";
 import DiscordProvider from "next-auth/providers/discord";
 import { PrismaAdapter } from "@next-auth/prisma-adapter";
-import { env } from "../env.mjs";
-import { prisma } from "./db";
+import { env } from "~/env.mjs";
+import { prisma } from "~/server/db";
 
 /**
  * Module augmentation for `next-auth` types.

Diff for: cli/template/extras/src/server/db.ts

@@ -1,6 +1,6 @@
 import { PrismaClient } from "@prisma/client";
 
-import { env } from "../env.mjs";
+import { env } from "~/env.mjs";
 
 const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
 

Diff for: cli/template/extras/src/utils/api.ts

@@ -10,7 +10,7 @@ import { createTRPCNext } from "@trpc/next";
 import { type inferRouterInputs, type inferRouterOutputs } from "@trpc/server";
 import superjson from "superjson";
 
-import { type AppRouter } from "../server/api/root";
+import { type AppRouter } from "~/server/api/root";
 
 const getBaseUrl = () => {
   if (typeof window !== "undefined") return ""; // browser should use relative url