next-yak 0.0.20 → 0.0.22

package/README.md

@@ -1,34 +1,22 @@
 # next-yak
 
-yet another CSS-in-JS library
-
-a CSS-in-JS with the power of "dynamic at the speed and reliability of static" 🙃
-
-the initial version of next-yak will only work for next.js
-
 ![Yak At Work as Frontend Dev](https://github.com/jantimon/next-yak/assets/4113649/2dcaf443-7205-4ef3-ba44-fbbe3ef2807d)
 
+[![npm version](https://badge.fury.io/js/next-yak.svg)](https://www.npmjs.com/package/next-yak)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jantimon/next-yak/blob/main/LICENSE)
 
-## Example
+**next-yak** is a CSS-in-JS solution tailored for [Next.js](https://nextjs.org/) that seamlessly combines the expressive power of styled-components syntax with efficient build-time extraction of CSS using Next.js's built-in CSS configuration.
 
-Try it on [stackblitz](https://stackblitz.com/edit/stackblitz-starters-dfykqy?file=app%2Fpage.tsx)
 
-```tsx
-import { styled, css } from "next-yak";
+## Features
 
-const Title = styled.h1<{ x: number; children: React.ReactNode }>`
-  display: block;
-  ${({ $x }) => $x % 2 === 0 && css`color: red`}
-  position: relative;
-  top: ${({ $x }) => `${$x * 100}px`};
-`;
+- **NextJs Compatibility**: Works smoothly with both React Server and Client Components
+- **Build-time CSS**: Reduces load time by handling CSS during the build phase, using Next.js built-in CSS Modules features
+- **Lightweight Runtime**: Operates with minimal impact, simply changing CSS classes without modifying the CSSOM
+- **Standard CSS Syntax**: Write styles in familiar, easy-to-use CSS
+- **Integrates with Atomic CSS**: Easily combines with atomic CSS frameworks like Tailwind CSS for more design options
 
-const App = () => (
-  <Title $x={3}>
-    Hello World
-  </Title>
-);
-```
+[Preview (Video)](https://github.com/jantimon/next-yak/assets/4113649/5383f60c-3bab-4aba-906c-d66070b6116c)
 
 ## Installation
 
@@ -36,9 +24,25 @@ const App = () => (
 npm install next-yak
 ```
 
+or
+
+```bash
+yarn add next-yak
+```
+
+## Getting Started
+
+Try it on [stackblitz](https://stackblitz.com/edit/stackblitz-starters-dfykqy?file=app%2Fpage.tsx)
+
+### Locally
+
+1. Install **next-yak** in your Next.js project.
+
+2. Add next-yak to your `next.config.js`:
+
 ```js
 // next.config.js
-const { withYak } = require("next-yak");
+const { withYak } = require("next-yak/withYak");
 
 const nextConfig = {
   // your next.js config
@@ -47,10 +51,114 @@ const nextConfig = {
 module.exports = withYak(nextConfig);
 ```
 
+3. Ready to go:
+
+```jsx
+// pages/index.js
+import { styled } from 'next-yak';
+
+const StyledDiv = styled.div`
+  color: #333;
+  padding: 16px;
+  background-color: #f0f0f0;
+`;
+
+function HomePage() {
+  return <StyledDiv>Hello, next-yak!</StyledDiv>;
+}
+
+export default HomePage;
+```
+
+## More Examples
+
+### Dynamic Styles
+
+Dynamic Styles will only toggle the css class during runtime:
+
+```jsx
+import { styled, css } from 'next-yak';
+
+const ToggleButton = styled.button`
+  ${props => props.$active
+     ? css`background-color: green`
+     : css`background-color: lime`
+  };
+  color: white;
+  padding: 10px 20px;
+`;
+```
+
+[Dynamic Styles (Video)](https://github.com/jantimon/next-yak/assets/4113649/c5f52846-33e4-4058-9c78-efd98197d75f)
+
+### Dynamic Properties
+
+Dynamic Properties use custom properties ([aka css variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)) under the hood to extract the CSS at built time but modify properties at runtime:
+
+```jsx
+import { styled } from 'next-yak';
+
+const ProgressBar = styled.div`
+  width: ${props => `${props.$percent}%`};
+  height: 20px;
+  background-color: #3498db;
+  transition: width 0.3s ease-in-out;
+`;
+
+const ProgressBarContainer = styled.div`
+  border: 1px solid #ccc;
+`;
+
+const ExampleComponent = () => {
+  const progress = 75; // You can dynamically set this value
+
+  return (
+    <ProgressBarContainer>
+      <ProgressBar $percent={progress} />
+    </ProgressBarContainer>
+  );
+};
+```
+
+[Dynamic Props (video)](https://github.com/jantimon/next-yak/assets/4113649/2fa78f82-382c-465f-b294-2504739ea168)
+
+
+### Targeting Components
+
+In next-yak, you can target other components directly using CSS selectors as long as they are **in the same file**:
+
+```jsx
+import { styled, keyframes } from 'next-yak';
+
+const flip = keyframes`
+  from { transform: rotateY(0deg); }
+  to { transform: rotateY(360deg); }
+`;
+
+const Glow = styled.div`
+  /* Add your Glow component styles here */
+`;
+
+const Text = styled.span`
+  display: inline-block;
+  ${Glow}:hover & {
+    animation: 1.5s ${flip} ease-out;
+  }
+`;
+
+const ExampleComponent = () => {
+  return (
+    <Glow>
+      <Text>This text will flip on hover.</Text>
+    </Glow>
+  );
+};
+```
+
 ## Nesting
 
 `next-yak` supports nesting out of the box.  
-Next.js 13 supports nesting only with the `postcss-nested` plugin.  
+[For now](https://github.com/css-modules/postcss-modules-local-by-default/pull/64) Next.js 13 supports nesting only with the `postcss-nested` plugin.  
 Therefore you have to create a `postcss.config.js` file in your project root:
 
 ```js
@@ -62,6 +170,8 @@ module.exports = {
 };
 ```
 
+[Nesting Example (video)](https://github.com/jantimon/next-yak/assets/4113649/33eeeb13-b0cf-499f-a1d3-ba6f51cf4308)
+
 ## Motivation
 
 Most of the existing CSS-in-JS libraries are either slow or have a complex api. This project tries to find a middle ground between speed and api complexity.
@@ -127,7 +237,7 @@ const Button = styled.button`
 
 ## Todos:
 
-This is a proof of concept. There are a lot of things that need to be done before this can be used in production:
+next-yak is currently in the development phase, with several todos that must be completed before it is ready for production:
 
  - [ ] improve js parsing - right now it not reusing babel..
  - [ ] better sourcemaps
@@ -150,6 +260,20 @@ This is a proof of concept. There are a lot of things that need to be done befor
   
 </details>
 
-## Prior art
+## Acknowledgments
+
+Special thanks to the contributors and the inspiring projects that influenced next-yak:
+
+  - Styled-Components 💅: For pioneering the styled syntax and redefining styling in the React ecosystem.
+  - Linaria: For its innovative approach to zero-runtime CSS in JS and efficient styling solutions.
+  - Emotion: For pushing the boundaries of CSS-in-JS and providing a high-performance styling experience.
+  - Vanilla Extract: For its focus on type-safe, zero-runtime CSS and contributing to the evolution of styling techniques.
+  - Tailwind CSS: For its exceptional atomic CSS approach, enabling efficient and customizable styling solutions.
+
+## License
+
+**next-yak** is licensed under the [MIT License](link/to/LICENSE).
+
+---
 
-This POC is heavily inspried by [styled-components](https://styled-components.com/), [emotion](https://emotion.sh/docs/introduction) and [linaria](https://github.com/callstack/linaria).
+Feel free to reach out with any questions, issues, or suggestions!