Add pagesDir config option.

[a-y-u-s-h]

Body

Currently Astro Pages are src/pages directory and there's no way to change it. It would be nice to be able to change it with a pagesDir config option.

Summary

Let's get a pagesDir option.

Background & Motivation

I'm using Astro as a backend as well in a project, where it makes less sense to have it named pages and more sense to call them routes on backend. I'm basically getting file based routing for creating endpoints without any frontend code. It just works and makes more sense, creates less clutter.

Goals

• Allow users to customize the directory for Astro Pages through a pagesDir configuration option.
• Provide flexibility in naming conventions for the pages directory, enabling users to choose more contextually relevant names such as 'routes' for backend applications.
• Reduce clutter and enhance project organization by accommodating varied project structures where 'pages' might not be the most fitting term.

[bluwy]

I'm not really sure about this feature. I think it's good that Astro provides some opinion here so it's predictable and consistent with other projects. Astro also has specific directory names that you can't change today, e.g. src/content, src/middleware, etc.

[a-y-u-s-h]

I too am not sure actually. A criticism of C++ as a language is that it provides too much flexibility and then projects end up with no standard conventions. But at the same time, I think pagesDir could serve a purpose. For purely API development projects made with Astro, it would be semantically more correct to call them routes, and if one day Astro upgrades from a Web-only framework to supporting mobile, then it could be renamed to screens, I don't know tbh. The default should still be pages. Since these options are opt-in, I don't think it should harm the opinions across the board.

[bluwy]

Documentation and external resources will likely be affected if we support custom directory names, so adding it isn't free. I think the slight confusing term if you're not using Astro conventionally, eg endpoints-only or mobile, isn't common for now to be worth adding the additional complexity. We could definitely revisit it if it's the few use cases that we want to formally support though, and provide a better name for them.

[a-y-u-s-h]

Makes sense.

[mvolkmann]

I would prefer to keep all source files that represent real UI pages in the "pages" directory for consistency across Astro projects.
But I would like for all things that do not represent UI pages, such as API endpoints, to go somewhere else.
Using a directory name like "apis" or "endpoints" for those would be great!

[a-y-u-s-h]

I think adding an option for pagesDir and another for API routes (say routesDir) would be nice because it'll cover all the conveniences (and purely server side use cases), like so -

1. If pagesDir and routesDir are the same and equal to "pages" (which I think should be the default) then it is compatible with how projects are being made so far with Astro. But since you can change it to routes, it'll keep others who like routes like Remix guys happy as well.

2. If you wish to write both frontend and backend code in a single project, but want to keep pages for the screens and routes for the endpoints, you can do so if these options are separate, which is your use cases, you can configure routesDir to endpoints or apis (I would personally choose routes, hehe)

3. For people like me, who many times don't like that they have to add server side dependencies in the same package.json as my frontend code, or would like to keep API and Frontend separate for many reasons (like: one API can power many frontends) or would like to only build a purely backend app with Astro with semantically correct naming for routes folder, having these two options would be great as well - I can simply delete pages folder and have routesDir point to routes.

That way Astro will be more versatile: Pure Frontend, Frontend + Backend, Pure Backend - all will have semantically correct folder names.

[natemoo-re]

Of course every team will have their preferences on what these directories should be called, but Astro does value providing strong and consist opinions on topics like this. For some context, when we landed on pages, Astro was purely a static site generator and we didn't support endpoints. Next and other frameworks had also been using this naming scheme for file-based routing at the time.

One thing that might be worth considering: instead of making src/pages/ configurable, would a new top-level src/api/ directory fit your use case? It's opinionated, but still provides a clear split between routes that generate HTML and routes that act as endpoints.

[mvolkmann]

I would love this! It seems the convention for subdirectories of src like pages is to make them plural, so maybe it should be apis.

[a-y-u-s-h]

I agree that pages should be named pages — personally I wouldn't change it in my config but if I pause and think along the lines of what's better for the framework rather than me — I would still, as a general developer prefer at least to have the flexibility to change the name of src/api (if not pages) because src/routes looks aesthetically and semantically better for some reason on backend (prior conditioning).

I also am of the opinion that these specific conventions should be mutable defaults (pages as well, because let's say in a hypothetical future we get a react native adapter some day; then mobile developers usually would semantically prefer to name their folder routes or screens or something else that sounds better). I get that there's a possibility of misusing or misunderstandings but that can be prescriptions in the documentation. Flexibility to change within config stops you from driving yourself crazy over semantics or disturbing your mental model once and for all when you're focused.

[bluwy]

For future reference, there was a PR sent but was closed: withastro/astro#9503

[kurdin]

This is a useful feature if you want to dynamically change pages folder on build time based on Env variables.
if anyone need this, here is a diff file. Just paste this to patches/astro+4.8.2.patch and run npx patch-package astro

diff --git a/node_modules/astro/dist/core/build/css-asset-name.js b/node_modules/astro/dist/core/build/css-asset-name.js
index 35cea9d..2f9e8b3 100644
--- a/node_modules/astro/dist/core/build/css-asset-name.js
+++ b/node_modules/astro/dist/core/build/css-asset-name.js
@@ -21,8 +21,8 @@ function createNameHash(baseId, hashIds) {
   return proposedName;
 }
 function createSlugger(settings) {
-  const pagesDir = viteID(new URL("./pages", settings.config.srcDir));
-  const indexPage = viteID(new URL("./pages/index", settings.config.srcDir));
+  const pagesDir = viteID(new URL(settings.config.pagesDir, settings.config.srcDir));
+  const indexPage = viteID(new URL(settings.config.pagesDir, settings.config.srcDir));
   const map = /* @__PURE__ */ new Map();
   const sep = "-";
   return function(id, ctx) {
diff --git a/node_modules/astro/dist/core/config/schema.js b/node_modules/astro/dist/core/config/schema.js
index e0cd109..ca94bdd 100644
--- a/node_modules/astro/dist/core/config/schema.js
+++ b/node_modules/astro/dist/core/config/schema.js
@@ -9,6 +9,7 @@ const ASTRO_CONFIG_DEFAULTS = {
   srcDir: "./src",
   publicDir: "./public",
   outDir: "./dist",
+  pagesDir: './pages',
   cacheDir: "./node_modules/.astro",
   base: "/",
   trailingSlash: "ignore",
@@ -55,6 +56,7 @@ const AstroConfigSchema = z.object({
   srcDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.srcDir).transform((val) => new URL(val)),
   publicDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.publicDir).transform((val) => new URL(val)),
   outDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.outDir).transform((val) => new URL(val)),
+  pagesDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.pagesDir).transform((val) => new URL(val)),
   cacheDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.cacheDir).transform((val) => new URL(val)),
   site: z.string().url().optional(),
   compressHTML: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.compressHTML),
@@ -342,6 +344,7 @@ function createRelativeSchema(cmd, fileProtocolRoot) {
     root: z.string().default(ASTRO_CONFIG_DEFAULTS.root).transform((val) => resolveDirAsUrl(val, fileProtocolRoot)),
     srcDir: z.string().default(ASTRO_CONFIG_DEFAULTS.srcDir).transform((val) => resolveDirAsUrl(val, fileProtocolRoot)),
     compressHTML: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.compressHTML),
+    pagesDir: z.string().default(ASTRO_CONFIG_DEFAULTS.pagesDir).transform((val) => resolveDirAsUrl(val, fileProtocolRoot)),
     publicDir: z.string().default(ASTRO_CONFIG_DEFAULTS.publicDir).transform((val) => resolveDirAsUrl(val, fileProtocolRoot)),
     outDir: z.string().default(ASTRO_CONFIG_DEFAULTS.outDir).transform((val) => resolveDirAsUrl(val, fileProtocolRoot)),
     cacheDir: z.string().default(ASTRO_CONFIG_DEFAULTS.cacheDir).transform((val) => resolveDirAsUrl(val, fileProtocolRoot)),
diff --git a/node_modules/astro/dist/core/util.js b/node_modules/astro/dist/core/util.js
index 6d5ac94..a6d03de 100644
--- a/node_modules/astro/dist/core/util.js
+++ b/node_modules/astro/dist/core/util.js
@@ -64,7 +64,7 @@ function unwrapId(id) {
   return id.startsWith(VALID_ID_PREFIX) ? id.slice(VALID_ID_PREFIX.length).replace(NULL_BYTE_PLACEHOLDER, "\0") : id;
 }
 function resolvePages(config) {
-  return new URL("./pages", config.srcDir);
+  return new URL(config.pagesDir, config.srcDir);
 }
 function isInPagesDir(file, config) {
   const pagesDir = resolvePages(config);

[illright]

I would like to advocate for this feature too. There is a frontend architecture methodology called Feature-Sliced Design (which I'm the maintainer of) and it has a concept of layers (folders) with standardized names. One of these names is pages, and the issue is that Feature-Sliced Design prescribes the use of a flat structure, with the routing done separately, whereas Astro's page directory is a nested structure.

Frameworks like Next.js, Remix, SvelteKit, and Nuxt.js also run up against this conflict, but there are ways to reconfigure the page directory to something like src/app/routes (with some caveats in Next.js), and not in Astro. That means that the users of FSD have to resort to hacks such as making a folder src/pages/_slices, and treat that as the FSD pages folder.

I think Astro's guidelines on project structure are very nice to have, but they should be opt-out-able, when you have a more comprehensive architectural solution to put in their place.

[florian-lefebvre]

I plan to use FSD soon and I think config based routing is the way here. There's an integration by @Fryuni that allows it easily https://inox-tools.fryuni.dev/custom-routing

[naourass]

I'm in favor of api folder to reside in src dir rather than pages dir. I think it's more relevant to separate frontend and backend stuff.

[intermundos]

Why put so rigid constraint on src structure? It would be great to have flexible, configurable directories structure to support different styles of project organization.

[dlandtaa]

I think that this is a pretty reasonable thing to request. I don't like having opinions on how I should organize my code forced upon me. For example, I would like to have this structure to my code:

/src
  - astro/
    - pages/
      - page1.astro
      - page2.astro
    - layouts/
      - layout1.astro
  - react/
    - component1.jsx
    - component2.jsx

but I can't and that's frustrating. Having src/pages as the default set up is fine but just give us a way to override it. You're welcome your opinions but let us have ours.

[KenEucker]

I am developing a framework where a Fastify API with an Astro admin panel will have plugins. Those plugins can already add routes to the fastify API by adding a routes directory that behave just as the fastify api does with filesystem discovery. I want my plugins to be able to do the same with a 'pages' folder that gets pages added to the astro admin without needing to modify the core of the framework in order to add pages.

There are concerns here to manage but in adding additional filepaths for discovering pages I am accepting responsibility for those concerns and would like to manage them in the way I see fit.

I think that the ability to create additional paths for pages to be discovered from is a feature that astro should have. Maybe changing the default path is not an option, but adding more paths definitely so.

[KenEucker]

To followup my use case with a note:

I have created an integration to my project to cover my use case and it is working as expected, however there is an npm package that may work for others located here:
astro-pages