Dolmen

Dolmen is a themeable UI component library designed to work with Solid.js and optimized for SSR (Server-side rendering). It provides a broad selection of UI components with minimal overhead.

Themes

Themes are implemented using Stitches and CSS variables. Once a theme has been defined, you can add it to any element (and it's descendants) by adding the theme's class to that element. There is no need for a theme provider or context.

Multiple themes are supported, so you can have (for example) a sidebar with a different color scheme than the main page.

Limitations of SSR

An important consideration when rendering HTML on the server is avoiding the ugly "Flash of Unstyled Content" (FOUC) when the HTML is displayed before the CSS is loaded. This requires that all of the CSS needs to be server-side renderable.

Dolmen uses the Stitches package to generate CSS stylesheets from JavaScript on the server as well as on the client.

One limitation of this approach is that the server-generated CSS is not quite as dynamic as CSS that is generated on the client. With client-side CSS-in-JS it is possible to create styles algorithmically, but with pregenerated CSS this can cause a combinatorial explosion of stylesheets unless care is taken to limit the number of combinations.

Dolmen provides some of the benefits of dynamic styling by cherry-picking the most common and useful style combinations and incorporating them into the component APIs, similar to what styled-system does. Here's an example:

<PageHeader gap="xs" flexDirection="row">
  <Button icon round>Sign In</Button>
</PageHeader>

However, what you can't do is something like this:

<PageHeader gap="10px">
  <Button icon round>Sign In</Button>
</PageHeader>

The reason is because the value 10px is not in the selected set of known gap sizes.

To get around this limitation, the component can be styled in the traditional way, by applying a conventional stylesheet:

<PageHeader class="page-header">
  <Button icon round>Sign In</Button>
</PageHeader>

// Stylesheet
.page-header {
  gap: 10px;
}

Dolmen does not put any restriction on what kind of stylesheets you use - it will work with SASS, vanilla-extract, Tailwind, or any other CSS technology out there. You can also use CSS-in-JS frameworks if you want, bearing in mind that you may be subject to FOUC issues unless you have a means to generate the stylesheet at build time.

Bottom line, what this means is that when using the styling properties in the component APIs, one should not expect that every possible CSS property will be available, but rather only the most popular ones. Since these style properties are all known TypeScript types, auto-complete in your editor can help you to discover which properties are available and what their allowed values are.

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a development server:

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

Solid apps are built with adapters, which optimise your project for deployment to different environments.

By default, npm run build will generate a Node app that you can run with node build. To use a different adapter, add it to the devDependencies in package.json and specify in your vite.config.js.

Um website completo desenvolvido com Next SSR, Typescript, Prismic CMS do tipo blog com diversas funcionalidades para interações entre os usuários.

Título: Spacetraveling Descrição: Um website completo desenvolvido com Next SSR, Typescript, Prismic CMS do tipo blog com diversas funcionalidades par

Dec 21, 2022

Comments

Bundling issues
Goal

The goal of the project is to produce a UI widget set that works well with Solid.js and SSR.

Requirements

No CSS-in-JS generated at runtime. This produces an ugly flash of unstyled content when the page is rendered on the server.

Users of the library should only have to bundle what is needed:

All JavaScript needs to be tree-shakeable.

CSS resources should not be prematurely bundled - instead, a separate CSS resource for each widget. If the user wants to combine CSS resources, they can do that in the bundler for their app.

Users of the library should not be constrained to using the same CSS framework as the library. Instead, the CSS bundled with the library should be static CSS that has already been processed.

Current Status

Currently I am using vanilla-extract to generate CSS resources from TypeScript at build time. There is a small amount of runtime for generating class name lists, but this is SSR-compatible.

Vanilla-extract requires a bundler - it will work with esbuild, Vite, Webpack, rollup, and some others. This means that in a production app, the library gets bundled twice: once at the library level, and once at the application level.

In order to work with Solid SSR, the library needs to provide something close to the original source, with the JSX tags preserved. However, at minimum the files in dist/ should be run through tsc, because the application may have a tsconfig.json with different compiler options. (Most tsconfig options don't affect how the code is written, but some - like isolateModules - can have an impact on how the code is written.)

Other than stripping type annotations and resolving stylesheet import references, the bundler at this level should do as little as possible.

Bundling Options

Here is a list of the various possible bundling options:

tsc - this is the simplest solution, unfortunately it doesn't work because there's no vanilla-extract plugin for tsc.

esbuild has nothing like a "preserveModules" option, meaning that the only option is to combine all JavaScript into a single output file. While this file is tree-shakeable, the problem is that there's no way to tree-shake CSS - the file has to include an import for every generated stylesheet, and the app has no way to exclude stylesheets that are not being used.

vite While vite does have a 'library mode', the problems are similar to esbuild: there's no way to generate individual modules for each source file.

rollup - there is both a vanilla-extract plugin and a preserve modules option. This almost works, however rollup isn't smart enough to preserve the '.jsx' extension on files containing JSX syntax. In other words, input files with the extension '.tsx' get mapped to '.js' even when the JSX option is set to "preserve". This causes the application-level bundler to choke.

There is a rollup plugin which can be used to customize output file extensions, however it is old, appears to be unmaintained, and I could not get it to work.

As you can see, none of these options currently work.

Alternatives

The most obvious approach is to abandon using vanilla-extract and re-write all of the stylesheets in SASS, possibly using CSS modules. However, in doing so I lost a lot of the benefits of vanilla-extract - type safety for CSS classes, dead code discovery, and so on.

In this case, I would probably then use plain tsc for generating the dist folder.
opened by viridia 1