docs(props): Immutability & Signals explanation and example.

[codyroberts]

Overview

The props section now clarifies that props are immutable and cannot be changed, and recommends readers to use signals in situations where the props need to be updated.

The example now shows two separate ways to use signals for props.

What is it?

• Feature / enhancement
• Bug
• Docs / tests / types / typos

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Use cases and why

• 1. Explains prop immutability
• 2. Recommends the use of signals
• 3. Gives examples of signal use

Checklist:

• My code follows the developer guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• Added new tests to cover the fix / functionality

[netlify]

👷 Deploy request for qwik-insights pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	77db77f

[wmertens]

Thank you for your contribution, improving the docs is always welcome, but props should generally not be signals.

An exception is the bind:value prop.

[wmertens]

This is not actually the case. The data is mutable, but unless you use signals or stores, there won't be a reactive change.
The props object itself is private to the component, it can also be mutated without problems, which might be handy when using props spreading.

[shairez]

@codyroberts maybe changing "immutable" to "non reactive" would be more accurate in that case?

@wmertens can you give a short example of the props spreading benefit please?

[codyroberts]

I tested it locally and I am still getting Error: Code(17): props are immutable when doing something simple like:

export const Item = component$<ItemProps>((props) => {
  props.price = 10;
  return (
    <ul>
      <li>name: {props.name}</li>
      <li>quantity: {props.quantity}</li>
      <li>description: {props.description}</li>
      <li>price: {props.price}</li>
    </ul>
  );
});

I was making this change to the documentation in response to this thread:
#6423

[wmertens]

@codyroberts ah indeed you're right, I didn't notice that before. So indeed the props object is shallowly immutable, but not deeply. This does not error:

import { component$ } from '@builder.io/qwik';

export const Foo = component$((props: any) => {
  // mutate a given prop
  props.bar.hello = 3

  return <button {...props}>A button</button>
})

export default component$(() => {
  return <Foo bar={{ hi: true }} />;
});

So deleting props isn't possible, you need to override via the props order.

[wmertens]

No, this is actually not a good idea. You should deference signals when you put them into props, and the optimizer will forward them.

Using signals as props is possible but it complicates the mental model and actual code without benefits.

[shairez]

@codyroberts so in Qwik, there's an optimization happening behind the scenes which allows you to use someProp={mySignal.value}

This won't actually create a subscription, but will pass the signal down for you and let you use that value wherever you need to use it and the subscription will be created for you.

@wmertens btw, it'll be "read only", meaning you can't really change that signal when you pass it's value as a prop.

If you want the ability to change it you need to pass it unwrapped (as the example shows) and then you can modify it.

[codyroberts]

Oh I see now, thank you!

If necessary I could probably make the documentation clearer about the fact that if you don't want to use a signal and don't need to modify the original value then you can create a local variable and set it to the props value, then change that.

[PatrickJS]

"I could probably make the documentation clearer" yes please

[shairez]

If necessary I could probably make the documentation clearer about the fact that if you don't want to use a signal and don't need to modify the original value then you can create a local variable and set it to the props value, then change that.

Thanks!
yeah most of the time if you just need the prop value you'd probably just de-structure it like:

component$(({something}: MyProps) => {
...
} )

// OR

const { something } = props;

That's what mostly we're seeing

[codyroberts]

@shairez @wmertens @PatrickJS

I tried to clarify the things we talked about, and added a couple examples and corresponding demos. Please let me know what you think!

[PatrickJS]

I'm good with everything so long as everyone else is

[gioboa]

Thanks for your help 👏

done

[shairez]

LGTM
Thanks @codyroberts ! 🙏

[pkg-pr-new]

Run & review this pull request in StackBlitz Codeflow.

@builder.io/qwik (77db77f)

npm i https://pkg.pr.new/@builder.io/qwik@6460

@builder.io/qwik-city (77db77f)

npm i https://pkg.pr.new/@builder.io/qwik-city@6460

eslint-plugin-qwik (77db77f)

npm i https://pkg.pr.new/eslint-plugin-qwik@6460

create-qwik (77db77f)

npm i https://pkg.pr.new/create-qwik@6460