https://github.com/Kotlin/Storytale
https://github.com/Kotlin/Storytale
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/Kotlin/Storytale
- Owner: Kotlin
- License: apache-2.0
- Created: 2024-05-06T10:21:23.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-17T13:13:41.000Z (7 months ago)
- Last Synced: 2024-12-17T13:26:36.856Z (7 months ago)
- Language: Kotlin
- Size: 559 KB
- Stars: 291
- Watchers: 17
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - Kotlin/Storytale - (Kotlin)
README
[](https://github.com/JetBrains#jetbrains-on-github)
# Storytale
Storytale is a Gradle Plugin designed to help developers to show their composables and develop them isolated by generating a gallery of the project components.
Check the `examples` and their generated web gallery [here](https://kotlin.github.io/Storytale)
Since Storytale is still in the early stages of development, the api is marked as unstable, but this section will also show you how to use `Storytale` to write code for your components, so let's get started! 🌟
## ⚙️ Getting Started
### 1. Setup
#### Import Dependencies
using Version Catalog
> **libs.versions.toml**
```toml
[versions]
storytale = "0.0.1+dev5"
[plugins]
storytale = { id = "org.jetbrains.compose.storytale", version.ref = "storytale" }
```
For the latest version check out the [Releases page](https://github.com/Kotlin/Storytale/releases)
> **build.gradle.kts** `root level`
```kotlin
plugins {
alias(libs.plugins.storytale) apply false
}
```
> **build.gradle.kts** `app level`
```kotlin
plugins {
alias(libs.plugins.storytale)
}
```
```kotlin
repositories {
mavenCentral()
maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
}
```
> [!NOTE]
> Storytale **has not** yet released its first version on `mavenCentral`. Currently, we publish dev builds to maven("https://maven.pkg.jetbrains.space/public/p/compose/dev"), so it's required to add this repository as shown above.
### 2. Create Sourcesets for Storytale on the target platform (for multi-platform projects)
Storytale can be used for Compose Multiplatform projects. To start using the Storytale API, you need to define a sourceset for the component you want to test (for example, it might only be used for `Android/iOS` platforms, or it could be common for all platforms).
In your app's 'src' folder, go to New -> Directory:
### 3. Usage
Now, your project structure will look like this:
```
└── src/
├── androidMain
├── commonMain
├── xxxxxStories/
│ └── kotlin
└── desktopMain
```
Let's try to write a simple function in `commonMain`:
`commonMain/PrimaryButton.kt`
```kotlin
@Composable
fun PrimaryButton(onClick: () -> Unit, enabled: Boolean = true) {
Button(onClick = onClick, enabled = enabled) {
Text("Click me!")
}
}
```
`commonStories/kotlin/PrimaryButton.story.kt`
```kotlin
import org.jetbrains.compose.storytale.story
val `PrimaryButton default state` by story {
val enabled by parameter(true)
PrimaryButton(onClick = {}, enabled = enabled)
}
```
Next, let's run the `desktopStoriesRun` command, you can find it in the `project/Storytale` section on the right side of the Gradle panel.
If you can't find all Gradle tasks containing `Storytale` after syncing, check if this option is enabled:
`settings->Experimental`
## Building and Contributing
Once the sync is successful, run `./gradlew publishToMavenLocal`.
At this point, if you see these Storytale `Gradle tasks`, it means you’ve successfully set up the project and can start contributing! :)
Before running `XXXXStoriesRun`, you need to run `./gradlew publishToMavenLocal` to deploy the latest changes if you've modified any part of the code (except for examples module)
#### About project structure
```
.
└── modules/
├── compiler-plugin
├── gallery
├── gradle-plugin
└── runtime
```
##### compiler-plugin
Includes the entry point of the Storytale compiler plugin and its related features.
##### gallery
The gallery represents the final, fully functional multi-platform application that is produced by Storytale.
##### gradle-plugin
All aspects related to building Storytale, including various Gradle tasks, generating Storytale apps for different platforms, and so on.
#### runtime
The runtime module is designed to provide developers with essential APIs during the coding process