We start with the existing guide. This is a perfect candidate for an interactive Stackblitz-based guide.

Problem

When the user is instructed to change the name of the Function from App to Bookshelf this breaks the Rendered function. The name "App" is still referenced in the index.jsx.

This is then referenced by the index.html file. to generate the App.jsx file.

All this can be found on lines 280 - 293

Solution

I think in order for the user to build the app fully they should be instructed on a few steps before adjusting the Function name. At least to show the relationship of the files mentioned.

• Maybe an explanation section going over the files right after the installation of Solidjs.
  • If you do this you can add an aside pointing to the instructions on how to edit the other files.
• Walk through the steps of editing the additional files.

When visiting the docs for the first time (or in Incognito) with a browser that prefers dark color schemes, the page correctly uses the dark theme, but the toggle button/icon does not. You'd have to click the button twice to switch to the light theme.

I believe this is caused by the theme toggle button depending on the mode property in the config context which is initially set to "none", since the button/icon only assumes the page is dark when config().mode is set to "dark".

A possible solution for this would be to initially set config().mode to either "light" or "dark" only instead of "none", depending on the browser's preferred color scheme.

CONTRIBUTING.md will describe our workflow and governance, and explain how to get started.
WRITING.md will explain our teaching philosophy, tone and accessibility requirements, and terminology.

The current iteration of the JSX section of the docs has a comparison with other frameworks. Among them is a comparison block to Vue the reads like the following:

Instead of JSX, Vue has its own "template language" that lives in a designated
spot in a .vue file. This serves a similar role to JSX, but isn't directly
integrated into JavaScript. In Solid, you can write a JSX element anywhere you
could write a JavaScript expression, and there's no enforced separation
between template and data.

However, there's a bit of nuance here that I think is potentially misleading without further explanation:

1. Vue does not require usage of .vue files. Instead, you can declare multiple Vue files within the same file by utilizing objects and/or the defineComponent API, either with the template property.

const Comp = {
    template: `<p>Hello world!</p>
}

2. Vue itself is capable of using JSX for production applications

Should we modify the existing language in any way to reflect these, or are they more considered "edge-cases" that are outside of the scope of our documentation?

Potential Impacts with Other Frameworks

3. The reason I raise the first point, in particular, is that Angular also has the ability to utilize a template field in the @Component decorator like so:

@Component({
selector: 'my-app',
template: '<p>Hello, world!</p>'
})
class AppComponent {}

And utilizes a compiler to convert this template into instructions. Would similar language to Vue's work here, with that in mind? Would we need to change the language for just Angular? For both Angular and Vue?

Guidance is appreciated 😄

Migrate from the existing docs, after the concept pages have been written. The API and concept pages should be interlinked, and much of @edemaine's explanations in the API reference will end up in concept pages (especially in Diving Deeper sections).

• Ability to nest "indefinitely"
• The root of a nest must be a page
• Divider lines with titles can be placed anywhere
• Mobile view that doesn't expand the entire TOC

On smaller screens (or when the number of sections/sections items increases) when you start scrolling you can see this bug:

Also, the current sidebar is following this semantic hierarchy structure:

h1 - Solid Docs header
h1 - Tutorials
--- h3 - Getting Started with Solid

The expected structure, that gives screen readers the best idea of the content organization would be:

h1 - Solid Docs header
-- h2 - Tutorials
--- h3 - Getting Started with Solid

This way, a screen reader user can easily navigate between the Solid Docs header link and the main content heading and also easily navigate between the upmost subsections of the page main content and the navbar upmost sections using heading shortcuts.

These are small problems that I have a PR ready fixing them.

The Nested Routing demo:

https://docs.solidjs.com/start/core-concepts/routing-and-pages#nested-routing

Let's consider a UI to help us out. Hover or tap each button to see how each segment of the URL maps to three things: a component layout, a JavaScript bundle, and a piece of data.

Some issues:

1. It wasn't obvious that it was a scrollable iFrame window. Not sure what 3 things you refer to in that entire page inside the iFrame.
2. The iFrame cannot be resized. It's frustrating. Especially if I'm supposed to find 3 specific things inside it.
3. The URL is not visible. So the demonstration fails.

Making the link invisible just confuses users and causes a really weird visual response, I think it would be better to change this for the same hover effect used in the Nav Sections for consistency. I will open a PR with this change.

Here's a gif demonstrating the issue:

While I understand the focus of JSX in our docs currently, one of the things that made Solid stand out to me initially (and helped distinguish it from compiler-based solutions like Svelte) was its ability to run its templating at runtime with the usage of @solid/html.

Would it be worthwhile to include an aside in our What is JSX section that indicates that JSX is not the only choice for Solid - simply the default pick?

• How to use a debugger statement
• solid-devtools

"Start by creating a new file in the src folder called: HelloWorld.jsx
Inside add the following:"

I figured there are some minor issues with color accessibility (the white text on light blue background for active items in the menu does not clear every accessibility test for example). There are also things that are hard to read in the nav bar mainly because of spacing and separators issues. I created a Figma file with prototypes in hope to fix some of the issues. I didn’t changed any of the structure so the changes will not introduce breaking changes (mainly padding and colors fixes). I believe the docs use tailwind so I used their colors to allow a quick implementation.

I think having a beautiful doc will help solid attract more and more people and would love to be part of that. I can start working on a PR to implement these modifications, but everyone can copy the Figma file and make their own modifications !

Describe the bug

After solidjs/solid#1032 I'm still playing with reconcile... let me report another issue I found.

An item unshifted is duplicated by reconcile:

const [state, setState] = createStore<any>({
  root: {
    id: "dummy",
    name: "",
    entries: []
  }
});
const root = {
  id: "id0",
  name: "ITEM 0",
  entries: [{ id: "id1",  name: "ITEM 1" }]
};
setState(reconcile({ root: root }, { key: null, merge: true }));
root.entries.unshift({ id: "id2", name: "ITEM 2 -- DUPLICATED!!!" });
setState(reconcile({ root: root }, { key: null, merge: true }));

console.log(state.root.entries[0].name); // ==> "ITEM 2 -- DUPLICATED!!!"
console.log(state.root.entries[1].name); // ==> "ITEM 2 -- DUPLICATED!!!"

(Note that the root property at the top-level is to workaround solidjs/solid#1032.)

Although I don't know the exact definition of merge: true, I think this is not an intended/expected behavior. As far as I confirmed, this duplication cannot be reproduced with one of the following modification:

• Use push but not unshift
• reconcile with merge: false
• reconcile with key: "id"
• Use a fresh new root object instead of reusing the value altered by root.entries.unshift

I guess there are some (undocumented) limitation around reusing values when merge: true... or essentially it's inappropriate for arrays modified with splice or unshift.

Your Example Website or App

https://playground.solidjs.com/?hash=575260739&version=1.4.1

Steps to Reproduce the Bug or Issue

1. Go to the above Playground
2. See the Result. The object including "name": "ITEM 2 -- DUPLICATED!!!" appear twice.

Expected behavior

• ITEM 2 is not duplicated

Screenshots or Videos

No response

Platform

• OS: Windows 11
• Browser: Edge
• Version: 101.0.1210.53

Additional context

No response

A step-by-step guide to building and deploying your Solid app. This will include "one-click" deployment options like Vercel and Netlify, GitHub pages, and more full-fledged production environments.

@davedbase can decide if Netlify gets a special/higher mention in this doc 😁

A self-contained guide answering the question: "How do I set up Vite for Solid from scratch?"
Includes Typescript setup and explains how Vite plugins work.

Describe the bug

There is a subtle issue when registering an event handler on an element when using hyper dom script.
When the handler has zero arguments like onClick() it will ever fire while this is not a problem onClick(e)

Your Example Website or App

solid/solid

Steps to Reproduce the Bug or Issue

function Button(props) {
  return h('button',props)
}

function App() {
  return [
    h(Button,{onClick(e){console.log('Hi')}}, "Ok"),
    h(Button,{onClick(){console.log('Hi')}}, "Fail")
  ]
}

Expected behavior

I would expect their not to be a difference in behaviour

Screenshots or Videos

No response

Platform

• Solid 1.4.3

Additional context

No response

Write concept pages that cover the following:

• Signals and Effects
  • Writing your own base primitive
• JSX Templates and Compiler-Created Effects
  • An explainer on how the compiler goes from JSX to JavaScript
• Memos
  • When and why do you use a createMemo
  • Motivated by expensive operation
• Advanced Primitives
  • createComputed
  • createRenderEffect

The <NavLink> component from solid-app-router is marking the Docs Header as the current page (aria-current="page") in all pages, not only docs.solidjs.com (expected behavior). Here's the current behavior and what would be expected or not:

docs.solidjs.com -> Docs Header is the current page ✅
docs.solidjs.com/tutorials/getting-started-with-solid/welcome -> Docs Header is the current page ❌ Welcome link is the current page ✅

Fortunately, we can fix this by adding the end={true} prop to NavLink. I have a PR ready with the fix.

After noticing one of our main pages ("Welcome") not having a <title> usage in #64, I think it would be a good to add a home-grown ESlint (or similar) rule to enforce this for new pages we add.

I'm assigning myself, since I've had a fair bit of experience with both ESlint and AST-based plugin creation

When you select any of the framework options (probably because the page content changes), you lose your current focused element (it goes back to the tabindex 0 element). This is very bad UX for keyboard-only and screen reader users. You would expect the change from the selected framework to just maintain your focus on the selected radio. This problem doesn't happen with the TypeScript/JavaScript radio group. Here's a gif that shows how I lost focus changing the framework but I don't lose it when I change the JavaScript/TypeScript radio:

I'm not sure why this is happening, so unfortunately I'm not going to submit a PR for this one.

Write concept pages that cover:

• createResource
• Suspense
• Error boundaries
• Transitions
• Invalidation

Source: https://www.youtube.com/watch?v=8Ou6domKfU4&t=900s

The way this reads could be more concise (See boxed text).

Text found here: Building UI With Components

• There's an error with 'you' instead of 'your'.
• When spelling out an acronym, it's clearer to capitalize expressed acronyms, such as "DOM" seen below.

As we learned above, Solid components return JSX. JSX is an HTML-like syntax used in Solid JavaScript code to represent part of the Document Object Model (DOM). In our HelloWorld.jsx example above, we returned the following JSX from our component:

The Discord and Edit icons are a bit misaligned, here's a screenshot:

This is a quick fix, so I'm going to PR the solution right now.

I wanted to contribute translations to the old docs but held off when I saw plans for a new docs site, since I wasn't sure about what would happen to the old docs.

However, in the new docs, I don't see any references to translation efforts/UI controls that allow for changing language.

Is the new docs still too early to consider i18n? And should people who want to contribute translations focus their efforts on the old site instead?

A guide answering the question: "How do I write idiomatic Solid code"?
I'd like to structure this in a step-by-step / progressive manner, rather than dumping a list of rules on the reader.

While speaking with @Jutanium, we touched on the idea of having images (and/or animations) to represent concepts that work with a visual medium (such as index tracking for For).

However, this raises the concern of consistency - it would be nice to have some common layouts and examples of what a chart/image would look like in docs usage.

Examples within the React ecosystem:

reactwg/react-18#46

Some thoughts:

• What about different types of file formats? (do we support SVG/PNG/PSD)
• Do we create different templates for different image manipulation software?
  • Do we enforce specific software for consistency?
    • Even SVGs have inconsistencies, say, between Adobe Illustrator and Figma exports

How to migrate from

• Vue
• Svelte
• React
• Angular

Some existing content here.

A how-to guide to creating and publishing a SolidJS library/package on NPM.

Migrate from the old site.

Some <nav> elements have the redundant role="navigation" attribute, which can lead to bugs in some screen readers and/or browsers. Also, we are currently using aria-label="Docs header navigation", this means that screen readers are reading this section like "Docs header navigation, navigation landmark" (tested in NVDA).

This is a quick fix that I have a PR ready to publish.

This answers the question: "How do I style my Solid app"? It will compare different approaches and provide a practical way to choose a solution for your project.

• Vite CSS
  • Vite CSS modules
• Tailwind, Windi, and Uno
• CSS-in-JS (build-time / static extraction)
• SCSS
• Runtime CSS-in-JS solutions

• Simple/client-fetching SSR
• Async SSR
• Streaming
• SSG
• Hydration

Assumes knowledge of the core framework. Teaches how to build an SPA and why Solid Start makes that easier.
Covers:

• Picking a styling method
• Understanding Vite
• Solid-app-router
• Code splitting
• Adding solid-start to an existing project (convergence point with SolidStart docs)

Ideally, this is an interactive tutorial that uses Vite in the browser with Stackblitz. @modderme123 and @nksaraf are looking into that infrastructure.

Building UI with Components > Passing props between components.

1. In this section "which are" are extra words. You can get straight to the point by removing them.

2. "you should use your own name" This is redundant. You can remove your own from the sentence.

Description
Let me start by saying fantastic job on the new docs page. It covers many more topics to get started with solid that a lot of people will find very helpful.

As promised my daily issue with the new docs page.

• The content table to the page's right doesn't auto-scroll to the intended page section.
• I couldn't find a page regarding why solid and how is it different from other frameworks

As suggested by @ryansolid in this twitter thread i'm opening this issue here on the docs.

We should document the behavior described in the twitter thread and in this SolidJS playground (https://playground.solidjs.com/?hash=667502849&version=1.4.1). I'm gonna rewrite the issue here.

If you try to set the same value for a signal it will smartly not rerun the effects associated with that signal. However this create a problem with the input if you try to programmatically limit the values.

This is because normally the input get's updated with the new value by the browser and later SolidJS re-update the value running the effect that keep in sync the value with the signal.

But as we stated if the value does not change the effect does not run again so the "browser wins".

You can "fix" this by specifing an equal function for the signal that always returns false (at the cost of a bit of performance).

I could work on this but i really don't know when so for the moment i'm just leaving this there.

As you can see, the 404 page has a width bigger than 100% of the available width, this creates a horizontal scrollbar:

Also, the 404 text itself isn't centered on mobile:

• I'm willing to submit a PR fixing this.

The Storybook API has changed quite a lot since Solid's Storybook docs were written in 2019. It would be really helpful (and I think go a loooong way toward helping drive adoption, long-term) if Solid could:

1. Update the docs to reflect the latest Storybook API (hopefully everything still works with 6.2+?)
2. Abstract all these manual setup steps away with an official Solid framework plugin for Storybook (docs for how to do this here: https://storybook.js.org/docs/react/api/new-frameworks)

Storybook's become a pretty essential piece of the UI development pipeline, and at least for me, official support for it is a prerequisite for seriously considering any frontend frameworks. I miiiight be able to help with setting this up for Solid, although I haven't tried adding support for a new framework to Storybook before. 😅

Explaining Solid's API design philosophy. Points from here, but heavily rework to be beginner-friendly:

• Declarative Data
• Vanishing Components
• Read/Write Segregation
• Simple is Better Than Easy

This will likely be in a special Concept page or a Foundation page.

This would provide in-place definitions for technical jargon, including Solid-specific terms. This can also link to Concept pages, and could even let you browse all usages of the word.

The existing reactivity guide is a good starting point: https://www.solidjs.com/guides/reactivity

We also have a new Tracking concept. Need to determine how these fit together (or if one should include the other): https://docs.solidjs.com/reference/tracking

After some discussion, the following topics are too advanced for this introduction to reactivity:

• Batching
• Proxies
• Owners

Concept guides on Context, Stores, and how to use the two together for state management.

Problem:

Previous discussion with @Jutanium on tone within the Docs. It's not the responsibility of the Docs to provide hype.

Solution:

Removing the exclamation mark on
src > routes > tutorials > getting-started-with-components.mdx
line: 184

Great first issue

This will cover best practices for creating accessible UIs with Solid. Can include solid-aria. More research required.

The problem

Currently, we're using file-based routing for our blog posts in order to define URL routing.

This leads to a problem where in order to find any given content, we have to navigate into:

src/routes/guides

Which is intermingled with source code and can be challenging to find for newcomer contributors that intend on solely contributing to our docs, and not our infrastructure codebase.

The solution

Per a discussion I had with @Jutanium, we would like to move to something of a similar model that I use for the Unicorn Utterances codebase where we have split root folders for these, like so:

• src - Where our infrastructure code lives
• content - Where our blog posts/documentation/etc lives

This means that in order to do this, we need to move away from file-based routing, and toward parameter-based routing.

I've started a WIP example branch here:

https://github.com/solidjs/solid-docs-next/tree/co-locate-guides

Hiccups in implementation

You'll notice that if you attempt to run the code in my branch, it will fail. This is because, as I understand it, the current codebase:

• Uses Vite to compile MDX and MD files down to TSX file equivalents
• Which then uses file-based routing in order to define the page URI

However, because our Vite plugin compiles MDX files to a function, this does not work. AFAIK, solid-start has the same limitations as NextJS's getServerSideProps in terms of required serialization going from the server to the client via routeData

In order to solve for this problem, I've previously (for UU, which uses NextJS):

1. Read the markdown files into a string
2. On the server, run an initial rehype instance in order to add some specific plugins and transformations
3. Passed that string to the client
4. Then on the client re-initialized the HTML string using rehype
5. Finally, took that AST and mapped it back to React (or in our case, Solid) components

This leads to a problem where our initial hydration of the page leads to duplicate data between the HTML passed to the client and the HTML that our second rehype instance runs into.

It's unclear what the best decision of overcoming this implementation detail would be. Advice/guidance would be greatly appreciated.

Once a decision is made on what to do next, I'm happy to work on the code to make this a reality.

https://docs.solidjs.com/how-to-guides/get-ready-for-solid/javascript-for-solid

When first writing modern JavaScript you might be tempted to use one of these keywords:
var, new, this, class

Then scroll down a little and it has an example with the new keyword:

const currentYear = new Date().getFullYear();

Its confusing, why use new after saying don't use it?