Docs: Limitations & runtime styles about compiled HOT 5 OPEN

Ah sorry for the delay.

Docs are very outdated - we've been focused on quite a few internal initiatives, and so we haven't had the chance to update our external-facing docs in a while. What hasn't been documented externally yet includes stuff like our move towards object notation, a more Emotion-like API (see below example) and as you mentioned, support for dynamic variables (which we don't really recommend internally anymore 😅). Updating our documentation is definitely on our todo list though 👀

For the time being, hopefully the following code will help for your code snippet:

// Object notation - what we recommend when using the styled API

export const Card = styled.span({
  color: (props) => props.$color,
  backgroundColor: (props) => props.color,
});

export const Text = styled.p({
  fontSize: `${(props) => props.$fontsize}px`,
  fontWeight: (props) => (props.level === 'h1' ? 700 : 600),
  gridColumn: (props) => props.gridColumn,
  margin: (props) => props.margin,
  textTransform: (props) => props.textTransform,
});

// However, we currently recommend using the Emotion-like css API,
// which has many restrictions imposed on it for performance

/** @jsx jsx */
import { css, jsx } from '@compiled/react';

export const cardStyles = css({
  color: (props) => props.$color,
  backgroundColor: (props) => props.color,
});

export const textStyles = css({
  fontSize: `${(props) => props.$fontsize}px`,
  fontWeight: (props) => (props.level === 'h1' ? 700 : 600),
  gridColumn: (props) => props.gridColumn,
  margin: (props) => props.margin,
  textTransform: (props) => props.textTransform,
});

// ...

export default function Home() {
  const [value, setValue] = useState(25);
  console.log(colors.primary);
  return (
    <span css={cardStyles}>
      <input
        value={value}
        type="number"
        onChange={(ev) => setValue(ev.target.value)}
      />
      <p css={textStyles} $fontsize={value}>
        In et felis viverra, egestas ligula nec, laoreet lacus. Nulla maximus
        orci vel diam mollis consectetur. Ut sed enim finibus, sollicitudin eros
        eu, venenatis metus. Nam in faucibus mi. Quisque euismod lobortis neque
        ac elementum. Aenean viverra erat enim, non vehicula sapien pharetra sit
        amet. Suspendisse potenti. In vitae ligula varius, efficitur dolor ut,
        pulvinar libero.
      </p>
    </span>
  );
}

For our use case we store some style values in DB, could we use compiled to interprete the fetched values and apply them on SSR? (we are using nextjs)

Hmm not sure, let me check with the rest of the team

from compiled.

Thanks for the example! I lpersonally like more the new css version btw.

Another question: You don't recommend the dynamic styling because of the performance drop? the FOUC?

Btw in your example there is a dynamic variable:
fontSize: `${(props) => props.$fontsize}px`, as the px can be an arbitrary value I guess they are not pre-compiled?

In our case we are not able to pre-compile the css classes because each user connected to the same nextjs app has a custom theme. We can create some base classes that we know are shared, but others will require runtime computing.

I was wondering if compiled is a good fit for that use case 👀, happy to hear what your team answers 😙

from compiled.

Hello! Btw the CSS version does not work dynamically with arbitrary runtime values https://stackblitz.com/edit/nextjs-olt3jd?file=src%2Fpages%2Findex.js
which i guess it's what the docs meant?

from compiled.

Re: #1553 (comment)

@dddlr Can you expand on this? Are you deprecating tagged template literals? What is the purpose of your recommendation?

I have two main reasons for preferring template literals:

1. They match the exact spec of css. This means code can be transferred to and from the browser, and the only documentation you need is the actual css spec.
2. They are faster to write because none of the values to be wrapped in quotation marks.

I understand that composition via template literals seems to have limited options in this library but am thus far willing to live with those limitations.

What's going on behind the scenes? I'm guessing the docs on this topic haven't been updated since your comment.

from compiled.

Are you deprecating tagged template literals? What is the purpose of your recommendation?

Yeah

A few reasons for this:

• Tagged template literals are harder to statically analyse than regular objects, especially when interpolations are used (which make things really tricky)
• Tagged template literals make it easy to accidentally write invalid CSS syntax (e.g. accidentally writing an extra closed brace)
• Object syntax prevents duplicate CSS properties being applied on one component (this is perhaps a less strong reason than the other two)

Our focus over the past couple of years has been on internal adoption of and migration to Compiled in our internal Atlassian codebases, and as such we prioritise providing support for our internal developers who are trying to migrate. This may trickle down to external documentation, but it depends on whether we have the time 😅 as any support we give for external developers has always been on a best-effort basis, and ultimately dependent on whether we have time outside our normal projects.

Two additional things I want to note here:

• Generally the direction we're moving Compiled towards is adding more restrictions and being much more opinionated on how styles can be written, in order to make styles more statically analyseable and to achieve better performance. You can see what these restrictions are in the work-in-progress(!) UI Styling Standard ESLint rules, which will govern how styling is written at Atlassian. I don't know much about your specific project, but there is a chance these restrictions may mean that Compiled is no longer the best option for your specific use case. (Just like how stylex's design intentionally is great for some use cases but not others.)

• I don't recall seeing any Next.js in the Atlassian codebases we're migrating, and so I don't think it's something we officially support? It might work, it might not work, I'm not sure...

from compiled.