diff --git a/docs/README.md b/docs/README.md index 1708e704..6bcd9a72 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,9 @@ - [Introduction](/README.md) - [Guides](/docs/guides/README.md) + - [Getting Started](/docs/guides/getting-started.md) - [Using `skpm` as a build system](/docs/guides/using-skpm.md) + - [Rendering](rendering.md) - [Data Fetching](/docs/guides/data-fetching.md) - [Universal Rendering](/docs/guides/universal-rendering.md) - [Styling](/docs/guides/styling.md) diff --git a/docs/guides/README.md b/docs/guides/README.md index 5c936c95..36cbc07b 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -2,7 +2,9 @@ How to use `react-sketchapp` for fun and profit. +- [Getting Started](getting-started.md) - [Using `skpm` as a build system](using-skpm.md) +- [Rendering](rendering.md) - [Data Fetching](data-fetching.md) - [Universal Rendering](universal-rendering.md) - [Styling](styling.md) diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md new file mode 100644 index 00000000..97119f7c --- /dev/null +++ b/docs/guides/getting-started.md @@ -0,0 +1,71 @@ +# Getting Started + +You can create a `react-sketchapp` project with `skpm`, by cloning a ready-made [example](../examples.md), or by manually setting up the `package.json` and `manifest.json` scripts (advanced usage). + +## Environment Setup + +You will need npm, Node and Sketch. + +- Terminal (if you’re new to the command line, this [guide](https://medium.com/32pixels/the-designers-guide-to-the-osx-command-prompt-71b0016cac31) may help) + - You need to make sure `git` is installed – type `git --version` in your Terminal to check if it's installed, if it isn’t, you should be prompted to install via “command line developer tools”. +- Code editor e.g. [VSCode](https://code.visualstudio.com/), [Atom](https://atom.io/) +- Node.js & `npm` – [install with Homebrew](https://nodejs.org/en/download/package-manager/#macos) (or install with [Node Version Manager](https://nodejs.org/en/download/package-manager/#nvm)) +- [Sketch](https://www.sketch.com/) + - requires macOS + +## Creating a Project With Skpm + +**Replace** `my-app` with your desired project name: + +### Installation + +```bash +npm install --global skpm +skpm create my-app --template=airbnb/react-sketchapp # template is a GitHub repo +cd my-app +``` + +### Setup + +You can now open `my-app` in your code editor of choice. You will see a `src` folder with a `manifest.json` file and Sketch entrypoint (e.g. `my-command.js`). If you wish to rename `my-command.js`, you can do so and update the file name in `script` in `manifest.json` + +Example modifications (assuming we want to rename the entrypoint file to `main.js` and don't want to have sub-commands): + +`src/manifest.json` + +```diff + "commands": [ + { +- "name": "my-command", ++ "name": "My App Name: Sketch Components" +- "identifier": "my-command-identifier", ++ "identifier": "main", +- "script": "./my-command.js" ++ "script": "./main.js" + } + ], + "menu": { +- "title": "my-app", +- "items": [ +- "my-command-identifier" +- ] ++ "isRoot": true, ++ "items": [ ++ "main" ++ ] ++ } + } +``` + +### Rendering to Sketch + +To render your app to Sketch, open the Sketch application, create a new blank document, then go to your Terminal and run: + +```bash +# Make sure you've already done `cd my-app` +npm run render +``` + +You can pass the target Sketch container layer (i.e. document, group or page object) to the `render` function in your Sketch plugin entrypoint file, using the Sketch API: `render(, sketch.getSelectedDocument()`. + +For more info on rendering to Sketch, see the [rendering](./rendering.md) page. diff --git a/docs/guides/rendering.md b/docs/guides/rendering.md new file mode 100644 index 00000000..f28d47b8 --- /dev/null +++ b/docs/guides/rendering.md @@ -0,0 +1,75 @@ +# Rendering Guide + +You can use the Sketch API to select Sketch containers such as documents, pages or groups, to pass through to the `render` function. + +### Rendering to Multiple Pages or New Documents + +`src/my-command.js` (or whatever file your Sketch plugin entrypoint is). + +```js +import React from 'react'; +import { render, Document, Page } from 'react-sketchapp'; + +// wrapper is required if you want to use multiple pages +const App = () => ( + + + + Hello World! + + + + + Hello World, again! + + + +); + +export default () => { + const documents = sketch.getDocuments(); + const document = + sketch.getSelectedDocument() || new sketch.Document(); // get the current document // or create a new document +}; +``` + +## Rendering to Selected Document + +This will render to the last active document. If there is no document open, document will be undefined and you will get an error, so you can add `|| new sketch.Document()` as a fallback to handle this. + +```js +import sketch from 'sketch'; +import { render } from 'react-sketchapp'; + +// const App = () => ... or import App from './App'; + +export default () => { + const document = sketch.getSelectedDocument(); + + render(, document); +}; +``` + +## Rendering to Document by Name + +We can select a document by name, by looping through `sketch.getDocuments()` and checking `doc.path` inside the loop. + +```js +import path from 'path'; +import sketch from 'sketch'; +import { render } from 'react-sketchapp'; + +// const App = () => ... or import App from './App'; + +const getDocumentByName = name => { + return (sketch.getDocuments() || []).find(doc => { + return doc.path && path.basename(doc.path, '.sketch') === name; + }); +}; + +export default () => { + const document = getDocumentByName('My App Design') || new sketch.Document(); // Fallback to new document if document not found + + render(, document); +}; +``` diff --git a/docs/guides/styling.md b/docs/guides/styling.md index b0347459..a4cea7b1 100644 --- a/docs/guides/styling.md +++ b/docs/guides/styling.md @@ -90,6 +90,7 @@ Components use CSS styles + FlexBox layout. | `textShadowOffset` | `{ width: number, height: number }` | ✅ | | `textShadowRadius` | `number` | ✅ | | `textShadowColor` | `Color` | ✅ | +| `textTransform` | `none` | `uppercase` | `lowercase` | ✅ | | `letterSpacing` | `number` | ✅ | | `lineHeight` | `number` | ✅ | | `textAlign` | `auto` | `left` | `right` | `center` | `justify` | ✅ |