Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation for all @compiled/ packages #1689

Merged
merged 7 commits into from
Jul 17, 2024
Merged

Update documentation for all @compiled/ packages #1689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
75ca2d5
Update Atomic CSS page to use object styles, not tagged template strings
dddlr Jul 12, 2024
f093606
Update @compiled/react documentation
dddlr Jul 12, 2024
31d5169
Update fonts
dddlr Jul 15, 2024
bfe1b82
Update remainder of @compiled/* documentation
dddlr Jul 15, 2024
df86247
Change Installation page to recommend Parcel
dddlr Jul 15, 2024
5a25c1d
Update title of 'Media queries and other at rules' to more easily fit…
dddlr Jul 15, 2024
cdf4be7
Address PR feedback
dddlr Jul 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions website/packages/docs/src/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,7 @@
<html lang="en">
<head>
<meta name="viewport" content="width=device-width" />
<link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin="" />
<title>Docs | Compiled CSS-in-JS</title>
<link
href="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@400&family=Roboto:wght@300;500&display=swap"
rel="stylesheet" />
<script async src="https://cdn.splitbee.io/sb.js"></script>
</head>
<body></body>
Expand Down
40 changes: 20 additions & 20 deletions website/packages/docs/src/pages/atomic-css.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,29 +104,29 @@ but they share the same atomic rule,
what happens?

```jsx
<div
css={css`
:hover {
color: blue;
}
:active {
color: red;
}
`}
/>
const styles = css({
'&:hover': {
color: 'blue',
},
'&:active': {
color: 'red',
},
});

<div css={styles} />;
```

```jsx
<div
css={css`
:active {
color: red;
}
:hover {
color: blue;
}
`}
/>
const styles = css({
'&:active': {
color: 'red',
},
'&:hover': {
color: 'blue',
},
});

<div css={styles} />;
```

The simple answer is it depends which component renders first!
Expand Down
38 changes: 20 additions & 18 deletions website/packages/docs/src/pages/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,28 @@ Then configure your bundler of choice or use [Babel](https://babeljs.io) directl

## Installation methods

### (Recommended) Parcel

Install the [Parcel v2](https://v2.parceljs.org) configuration.

```bash
npm install @compiled/parcel-config --save-dev
```

Add the compiled preset to your [Parcel config](https://parceljs.org/features/plugins/).

```json
{
"extends": ["@parcel/config-default", "@compiled/parcel-config"]
}
```

See the [configuration package docs](/pkg-parcel-config) for configuration options.

### Webpack

> We recommend Parcel, as this will be more performant, and it aligns with the Atlassian recommended tech stack.

Install the [Webpack](https://webpack.js.org/) loader.

```bash
Expand Down Expand Up @@ -52,24 +72,6 @@ Read the [Webpack CSS extraction](/css-extraction-webpack) for a step-by-step gu

See the [loader package docs](/pkg-webpack-loader) for configuration options.

### Parcel

Install the [Parcel v2](https://v2.parceljs.org) configuration.

```bash
npm install @compiled/parcel-config --save-dev
```

Add the compiled preset to your [Parcel config](https://parceljs.org/features/plugins/).

```json
{
"extends": ["@parcel/config-default", "@compiled/parcel-config"]
}
```

See the [configuration package docs](/pkg-parcel-config) for configuration options.

### Babel

> **Local development** <br />
Expand Down
4 changes: 2 additions & 2 deletions website/packages/docs/src/pages/media-queries-and-other-at-rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
section: 50-Guides
name: Media queries and other at-rules
name: Media queries, other at-rules
---

# Media queries and other at-rules
# Media queries, other at-rules

Media queries and other at-rules (e.g. `@layer` and `@supports`) are sorted based on a simplified version of the mobile-first sorting algorithm used by the [`sort-css-media-queries`](https://github.com/olehdutchenko/sort-css-media-queries/) library.

Expand Down
31 changes: 19 additions & 12 deletions website/packages/docs/src/pages/pkg-babel-plugin-strip-runtime.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,29 +29,26 @@ Configure in your Babel config.
}
```

### onFoundStyleRules: (rules: string[]) => void

Will callback at the end of a file pass with all found style rules.

### compiledRequireExclude: boolean
#### compiledRequireExclude

When set will prevent additional require (one import per rule) in the bundle and add style rules to meta data.
This could be used when enabling style sheet extraction in a different configuration for SSR.

Defaults to `false`.

### extractStylesToDirectory
- Type: `boolean`
- Default: `false`

extractStylesToDirectory?: \{ source: string; dest: string \};
#### extractStylesToDirectory

When set, extracts styles to an external CSS file. This is beneficial for building platform components that are to be published on NPM.

Example of useage:
Example of usage:

Given the below folder structure:

```
- src
- index.jsx
```

```js
// src/index.jsx
Expand All @@ -72,9 +69,11 @@ Set the source folder and output folder relative to the root project path.

It extracts the CSS sheet to a seperate file.

```
- dist
- index.js
- index.compiled.css
```

```js
// src/index.jsx
Expand All @@ -91,10 +90,18 @@ const Component = () =>
);
```

### sortAtRules: boolean
- Type: `{ source: string; dest: string }`
- Default: `undefined`

#### styleSheetPath

An internal option used by other Compiled plugins. Don't use this!

#### sortAtRules

Whether to sort at-rules, including media queries.

See [here](/media-queries-and-other-at-rules) for more information.

Defaults to `true`.
- Type: `boolean`
- Default: `true`
107 changes: 92 additions & 15 deletions website/packages/docs/src/pages/pkg-babel-plugin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,41 +41,118 @@ Configure in your Babel config.
}
```

### importReact: boolean
If you choose to configure Compiled through Webpack or Parcel (recommended), you can pass options for `@compiled/babel-plugin` through those configurations. See [`@compiled/webpack-loader`](/pkg-webpack-loader) and [`@compiled/parcel-config`](/pkg-parcel-config) for more information.

Will import React into the module if it is not found.
When using `@babel/preset-react` with the [automatic runtime](https://babeljs.io/docs/en/babel-preset-react#react-automatic-runtime) this is not needed and can be set to `false`.
`@compiled/babel-plugin` supports the following options:

- `addComponentName`
- `cache`
- `classNameCompressionMap`
- `extensions`
- `importReact`
- `importSources`
- `increaseSpecificity`
- `nonce`
- `onIncludedFiles`
- `optimizeCss`
- `parserBabelPlugins`
- `processXcss`
- `resolver`
- `sortAtRules`

#### addComponentName

Defaults to `true`.
Add the component name as a class name to the DOM in non-production environments, if `styled` is used.

### cache: boolean | 'single-pass'
- Type: `boolean`
- Default: `false`

#### cache

Will cache the result of statically evaluated imports.

- `true` will cache for the duration of the node process
- `'single-pass'` will cache for a single pass of a file
- `false` turns caching off

Defaults to `true`.
* Type: `boolean | 'single-pass'`
* Default: `true`

#### classNameCompressionMap

### optimizeCss: boolean
Don't use this!

Will run additional cssnano plugins to normalize CSS during build.
An internal and experimental option used to compress class names.

Defaults to `true`.
Note that in `@compiled/webpack-loader` and `@compiled/parcel-config`, `classNameCompressionMap` requires `extract` to be true as well.

### onIncludedFiles: (files: string[]) => void
#### extensions

Will callback at the end of a file pass with all imported files that were statically evaluated into the file.
Extensions that we should consider code. We use these to identify if a file should be parsed.

### addComponentName: boolean
- Type: `string[]`
- Default: `['.js', '.jsx', '.ts', '.tsx']`

Add the component name as class name to DOM in non-production environment if styled is used.
#### importReact

Will import React into the module if it is not found.
When using `@babel/preset-react` with the [automatic runtime](https://babeljs.io/docs/en/babel-preset-react#react-automatic-runtime) this is not needed and can be set to `false`.

Default to `false`
- Type: `boolean`
- Default: `true`

### importSources: string[]
#### importSources

Additional libraries that should be parsed as though they were `@compiled/react` imports.

Specifying this is important if you are using Compiled APIs through another package using the `createStrictAPI` function.

- Type: `string[]`
- Default: `undefined`

#### increaseSpecificity

An experimental option that increases the specificity of all generated Compiled classes. Don't use this!

#### nonce

[Security nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) that will be applied to inline style elements if defined.

- Type: `string`
- Default: `false`

#### onIncludedFiles

An internal option. Callback fired at the end of the file pass when files have been included in the transformation.

- Type: `(files: string[]) => void`
- Default: `undefined`

#### optimizeCss

Will run additional `cssnano` plugins to normalize CSS during the build.

- Type: `boolean`
- Default: `true`

#### parserBabelPlugins

Babel parser plugins to be used when parsing the source code. Define these to enable extra babel parsers (for example, typescript).
See the [babel docs](https://babeljs.io/docs/en/plugins/#syntax-plugins) for more context.

Usually, you will set this option through [`@compiled/parcel-config`] or [`@compiled/webpack-loader`](/webpack-loader) -- see there for examples.

#### processXcss

An option we are only using internally. Don't use!
Copy link
Collaborator Author

@dddlr dddlr Jul 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if there's any point documenting internal options... i've erred towards including them just so we can use the docs as a single source of truth

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's fine to be honest, probably helps the internal team as well, eh?


#### resolver

A custom resolver used to statically evaluate import declarations, specified as either an object or module path. If this is an object, it should contain a `resolveSync` function with the following type signature: `(context: string, request: string) => string`.

- Type: `string | Resolver`
- Default: `undefined`

#### sortAtRules

Unused.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reckon dealing with stuff that's unused, deprecated, obsolete etc would be out of scope of this PR - as a website/docs-focussed PR, I want to avoid making changes to the Compiled packages

I've made an issue so that we can properly clean these up in the future #1690

2 changes: 1 addition & 1 deletion website/packages/docs/src/pages/pkg-eslint-plugin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,4 @@ export default [

## Rules

See [here](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin) for a list of rules in `@compiled/eslint-plugin`.
See [here](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin) for a non-exhaustive list of rules in `@compiled/eslint-plugin`.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracked through #1691

Loading
Loading