Docz: Use config.base when starting dev server (v2)

[Dangoo]

Hi,

currently when making a static build using a custom base path in doczrc.js, it is possible to run the site e.g. on github pages as stated in the docs.
But that base path is also used for local development while the docz dev command will always open the browser on /.

What do you think of using the base also for starting the local browser?
https://github.com/doczjs/docz/blob/221d448f861a90037a3f35d475e3fcac1a6e2e98/core/docz-core/src/bundler/machine/services/exec-dev-command.ts#L8-L21

Besides that, why is this behavior implemented in a customized way like that even with gatsby under the hood (instead of using gatsby serve)?

Seems like the people over at gatsby had a similar issue: https://github.com/gatsbyjs/gatsby/issues/5271

[rakannimer]

Hello,

But that base path is also used for local development while the docz serve command will always open the browser on /.

I'm a bit confused here, I think you mean the docz dev command ? The code you're pointing to runs when you call docz dev and the docz serve command doesn't open your browser.

For the rest, I'll assume you mean dev, please correct me if I'm missing something.

But that base path is also used for local development while the docz dev command will always open the browser on /.

Yep this definitely adds friction to the user

What do you think of using the base also for starting the local browser?

I like that ! Under the hood the dev command is very simple :

It cds into .docz directory and calls yarn dev --port 3000 which maps to gatsby develop --port 3000 waits until port 3000 is open and then opens a browser with the provided url

gatsby develop doesn't support opening the browser in a specific path, if I'm not mistaken, but since we're using a custom open browser method it shouldn't be too hard to open a url built with the base config argument.

Are you're interested in taking this on ?

[Dangoo]

I'm a bit confused here, I think you mean the docz dev command ?

Yeah sorry, my bad. The whole mapping stuff is messing with my head 😄

but since we're using a custom open browser method it shouldn't be too hard to open a url built with the base config argument.

Thats right! Something like http://${args.host}:${args.port}${args.base ? args.base : ''} should do the job.

BUT:
Fiddling around with base path brought some other insights:

• using conifg.base generates the whole page in a sub directory and does not only prefix the link targets
• instead using {prefixPath: '/custom/'} in gatsby-config.js with gatsby build --prefixPaths does the job well

So I'm not even sure whether either config.base works like expected and is just meant for another usecase or has some issues in the current implementation?
Anyways for my desired effect with the prefixed link targets the generated .docz/package.json should include --prefixPaths option, when pathPrefix is specified in gatsby-config.js.
https://github.com/doczjs/docz/blob/221d448f861a90037a3f35d475e3fcac1a6e2e98/core/docz-core/src/bundler/machine/services/create-resources.ts#L27

[rakannimer]

Anyways for my desired effect with the prefixed link targets the generated .docz/package.json should include --prefixPaths option, when pathPrefix is specified in gatsby-config.js

So you're suggesting,

1. For docz dev config.base is ignored and the docs are served to base "/"
2. For the build process we add --prefixPaths if a prefixPath variable is specified in gatsby-config.js
3. Deprecate config.base in favor of using pathPrefix in gatbsy-config.js

I think it would be easier to use config.base only, to decide if we should use pathPrefix or not when building, to help people migrating from v1.

We'd have to remove the behavior you described :

using config.base generates the whole page in a sub directory and does not only prefix the link targets

And pass the config object the build command

From here:

https://github.com/doczjs/docz/blob/7b31589cdbd2f434917f4e833537c4c5452dee1f/core/docz-core/src/commands/build.ts#L19

to here :

https://github.com/doczjs/docz/blob/7b31589cdbd2f434917f4e833537c4c5452dee1f/core/docz-core/src/bundler/build.ts#L12-L13

and change the command from yarn build :

- spawn.sync('yarn', ['build'], { stdio: 'inherit' })
+ spawn.sync('yarn', ['build', config.base?'--prefixPaths':''], { stdio: 'inherit' })

And last, add pathPrefix to the generated gatsby config file :
https://github.com/doczjs/docz/blob/7b31589cdbd2f434917f4e833537c4c5452dee1f/core/docz-core/templates/gatsby-config.tpl.js

You're right this is much bigger than I assumed 😄

[Dangoo]

Wasn't suggesting anything - just mentioning. But your approach sounds reasonable.
So following things to do (worked quite well with the list the last time):

• Prevent config.base from influencing the output structure
• Pass config to bundler/build.ts
• If config.base is set, apply option --prefixPaths to build command (and thus to gatsby build)
• Copy config.base as pathPrefix to gatsby-config.tpl.js

I'll see what I can do :)

[rakannimer]

Awesome ! Take your time and no pressure at all :)

[Dangoo]

Hey @rakannimer,

started to work on #1103 today and got everything working so far except for the issue described above:

using config.base generates the whole page in a sub directory and does not only prefix the link targets

Honestly I'm not quite sure where that option is being passed down to gatsby build and how that could affect the page generation…

Could you give me a hand here?

[rakannimer]

Hello @Dangoo,

I think the base parameter is being passed down to the gatsby-theme-docz in the generated .docz/gatsby-config.js and gatsby-theme-docz is then using it to set the build output path.

newConfig here is being passed down as opts to the gatsby-config template :

https://github.com/doczjs/docz/blob/3279760144bcdbbcdae3189049f355901cf9e959/core/docz-core/src/bundler/machine/services/create-resources.ts#L53

The gatsby-theme-docz package then passes the config to the Entries instance here : https://github.com/doczjs/docz/blob/3279760144bcdbbcdae3189049f355901cf9e959/core/gatsby-theme-docz/lib/sourceNodes.js#L18

which creates an entry for each file.

The entry sets its route property based on the base config :
https://github.com/doczjs/docz/blob/3279760144bcdbbcdae3189049f355901cf9e959/core/docz-core/src/lib/Entry.ts#L70

and last, entries are used in the Gatsby theme to source new Gatsby nodes : https://github.com/doczjs/docz/blob/3279760144bcdbbcdae3189049f355901cf9e959/core/gatsby-theme-docz/lib/sourceNodes.js#L59

[rakannimer]

We can change this in the Entry object by replacing config.base with /

- this.route = this.getRoute(parsed, config.base);
+ this.route = this.getRoute(parsed, "/"); // Set as / and use gatsby prefixPaths

What do you think ?

[Dangoo]

We can change this in the Entry object by replacing config.base with /

Sounds like the way to go! I'll give it a try, thanks.

[Dangoo]

Worked out quite well, so #1103 is ready for review :)

Specifying pathPrefix in custom gatsby-config.js can lead to a little but expected side effect though (not bad, just to mention):

• using config.base "activates" the usage of --prefixPaths for gatsby build and gatsby serve
• during build the .docz/gatsby-config.js is generated from config, potentially containing prefixPath from config.base
• adding a custom gatsby-config.js to your project specifying prefixPath will be merged from generated gatsby-config.custom.js
• resulting prefixPath will be the one from gatsby-config.js instead of config.base

[rakannimer]

👍 Merged and released as 2.0.0-rc.40

[lettertwo]

Does this change break the gatsby-theme-docz use case where you want to add docz to an existing Gatsby site? For example, a gatsby-config.js like:

module.exports = {
  siteMetadata: {
    title: 'Some Gatsby site',
    description: 'This is a Gatsby site that has other pages, not just docz',
  },
  plugins: [
    {
      resolve: 'gatsby-theme-docz',
      options: {
        title: 'Some Gatsby Site Docz',
        description: 'Docz for Components used to build the other pages in the Gatsby site',
        base: '/components/',
      },
    },
    // ... other gatsby plugins and themes here
    //  These other plugins and themes might create other pages.
  ],
}

Prior to 2.0.0-rc.40, this would result in all of the docz pages living under /components/, along side any other Gatsby pages. Importantly, this meant that there was no danger of overlap in pages between docz and any other plugins/themes. Now, the docz pages are being flattened into the Gatsby site, resulting in collisions, the most likely of which is the docz index _overwriting_ the Gatsby site's index page (conventionally located at /src/pages/index.jsx).

Is there a way to meet this use case after rc.40?