Improve extensibility of custom themes

[goedelsoup]

Is your feature request related to a problem? Please describe.

During my implementation of a custom theme, two key challenges arose:

Tailwind not composable for external libraries

One large selling point to me as an end-user of Nextra is the consistency of design patterns across themes which serve common development task for me within my projects. Composition is currently implemented through directory-based references, as is done here in the nextra-theme-blog module.

While I was able to use CSS imports to resolve some issues in inheriting style elements from nextra-theme-docs, it did not produce the intended results.

autoImportThemeStyle should apply to all module-based themes

Due to the guard on internal themes when determining whether to include the default stylesheet in imports, any custom themes described as module dependencies do not work by default.

While this can be worked around by including import '@packages/nextra-theme-resume/style.css'; in the _app.tsx for the site, end users who may be consuming third-party themes may encounter unexpected behavior when following the existing Nextra docs.

Describe the solution you'd like

Style composition between themes

For the issues with Tailwind composition, I don't have enough hands-on experience with the related tooling to confidently describe an appropriate fix in detail. Given that context, what I recommend structurally is:

1. Short-term: Include tailwind.config.ts in exports to allow use by external code
2. Long-term: Maintain public, inheritable styles and components in a nextra-theme-base package

I do see changes to the style composition and build workflow in v4; I'm unsure of the intersection of those changes and the problem presented here.

Auto-import styles

For the behavior of autoImportThemeStyle, I would like to see the conditional requiring the theme to exist internally to be replaced with the isLocalTheme variable.

If implemented as above, I believe this should be a non-breaking change for all end-users; users using internal themes will still import the same stylesheet and those using a local theme will have already imported their stylesheets through other mechanisms. The benefit will be for module-based themes, which will now work by default when following the convention of exporting the theme's default stylesheet as ./styles.css.

Describe alternatives you've considered

I've implemented workarounds for the time-being for each problem and am happy to document them in more detail. I am also happy to test a refactor to v4 if the solutions may already exist there.

Additional context

Happy to put together a PR for the changes but was unsure of the status of v4 and the approaches to take here.

[dimaMachina]

Hi, thanks for your issue!

While I was able to use CSS imports to resolve some issues in inheriting style elements from nextra-theme-docs, it did not produce the intended results.

does CSS layers not fix this issue for you? https://nextra.site/docs/guide/advanced/customize-the-cascade-layers

For the behavior of autoImportThemeStyle, I would like to see the conditional requiring the theme to exist internally to be replaced with the isLocalTheme variable.

autoImportThemeStyle option was removed, in v4 users should manually import style.css in root layout.jsx/tsx file

If implemented as above, I believe this should be a non-breaking change for all end-users; users using internal themes will still import the same stylesheet and those using a local theme will have already imported their stylesheets through other mechanisms. The benefit will be for module-based themes, which will now work by default when following the convention of exporting the theme's default stylesheet as ./styles.css.

I do not plan to add new features in v3 since the development of v4 is done and the first rc.0 with blog post announcement will be released soon

I've implemented workarounds for the time-being for each problem and am happy to document them in more detail. I am also happy to test a refactor to v4 if the solutions may already exist there.

I would be happy if you try v4, and create a proposal and feature for Nextra 4.
Also, I would be happy if you improve the docs for Nextra v4 and the docs for the custom theme as well 🙏.

You can take a look at the docs' last preview in Nextra v4 PR (just click to View deployment)

https://nextra-v2-bg3pcxvcw-shud.vercel.app/

Some helpful info about Nextra 4, I described in #3675 (comment)

Also, you can take a look at migrated examples and migrated nextra.site website source code

Thank you!