You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When you [install shiny](get-started/install.qmd), you will have access to the `shiny` command line interface (CLI).
6
+
You can use this interface to help you create and run your Shiny applications.
7
+
8
+
## Create a Shiny application
9
+
10
+
The best way to create a new Shiny app is with the `shiny create` command line interface.
11
+
This command asks you a series of questions about what kind of app you want to create,
12
+
and then provides all the boilerplate code you need to get started with a working app.
13
+
14
+
```bash
15
+
shiny create
16
+
```
17
+
18
+
{class="img-shadow"}
19
+
20
+
::: callout-tip
21
+
### Copy/paste examples
22
+
23
+
If you find an example on this site that you want to run or edit locally,
24
+
you can use the following command to get a basic app template,
25
+
then copy and paste the code from the example into the template.
26
+
27
+
```bash
28
+
shiny create --template basic-app -m express
29
+
```
30
+
:::
31
+
32
+
33
+
## Run
34
+
35
+
Shiny apps can be launched from Positron, VS Code, or the command line via `shiny run`.
36
+
37
+
::: {.callout-tip}
38
+
#### Name your app `app.py`
39
+
40
+
We recommend naming your shiny application `app.py`.
41
+
This is the default file that `shiny run` will look for, so you can run the application in the terminal without any additional parameters.
42
+
43
+
If you need a more unique name, we recommend beginning the file with `app`, so the shiny extension can still run with a [play button click](install.qmd#positron).
44
+
:::
45
+
46
+
### Positron and VS Code
47
+
48
+
The best way to run (and develop) Shiny apps is in [Positron][positron] or [Visual Studio Code][vscode] with the [Shiny extension][vscode-shiny].
49
+
When a Shiny `app.py` file is being edited, the default behavior of the Run button (circled in red in the screenshot below) becomes "Run Shiny App".
50
+
51
+
52
+
53
+
This launches a Python process in a dedicated terminal instance, and a captive web browser.
54
+
This lets you test your app without leaving your editor, and whenever you make changes to your app's source, the preview will update. To preview your app in a full browser, click the icon to the right of the URL bar to launch the app in an external browser.
55
+
56
+
Next to the Run button is a dropdown menu that lets you "Debug Shiny App". This launches the app in debug mode, which lets you set breakpoints and step through your code.
57
+
See the [debugging](debug.qmd) section for more information.
58
+
59
+
### Command line
60
+
61
+
To run a Shiny app from the command line, use the `shiny run` command.
62
+
This command takes a single argument, the path to the app's entry point.
63
+
For example, if your app's entry point is `app.py` in the directory `./app_dir`, you can run it like this:
64
+
65
+
```bash
66
+
shiny run --reload --launch-browser app_dir/app.py
67
+
```
68
+
69
+
This should start your app and also automatically launch a web browser.
70
+
71
+
The `--reload` flag means that file changes in the current directory tree will cause the Python process to restart and the browser to reload.
72
+
Update and save changes to `app.py` and then wait a moment for the changes to appear in the browser.
73
+
74
+
With these two `shiny` commands, you now have a project that you can run in your terminal.
75
+
You can use any text editor or Python IDE to write Shiny apps, but we've taken special care to ensure a smooth workflow for [Positron][positron] and [Visual Studio Code][vscode].
Copy file name to clipboardExpand all lines: get-started/debug.qmd
+1-3Lines changed: 1 addition & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -57,11 +57,9 @@ The error displayed in the app is only the final part of the stack trace, but th
57
57
When Shiny apps are deployed, error messages are sanitized to the eliminate the possibility of leaking sensitive information. To unsanitize error messages, you'll need to set `sanitize_errors=True` in the `App` constructor (of a [Shiny core app](express-vs-core.qmd)).
58
58
:::
59
59
60
-
61
-
62
60
## Debugging
63
61
64
-
### VS Code debugger
62
+
### Positron and VS Code debugger
65
63
66
64
The [VS Code debugger](https://code.visualstudio.com/docs/editor/debugging) is a powerful tool for debugging Python code.
For production apps, we recommend using a virtual environment to manage your dependencies. In this case, you should install `shiny` in your virtual environment scoped to your app, rather than globally. For example, if you are creating an app in a directory called `myapp`, you would create a virtual environment in that directory and install `shiny` there:
35
+
For production apps, we recommend using a virtual environment to manage your dependencies.
36
+
In this case, you should install `shiny` in your virtual environment scoped to your app, rather than globally.
37
+
For example, if you are creating an app in a directory called `myapp`, you would create a virtual environment in that directory and install `shiny` there:
37
38
38
39
```bash
39
40
mkdir myapp
40
41
cd myapp
42
+
41
43
# Create a virtual environment in the .venv subdirectory
42
44
python3 -m venv .venv
45
+
43
46
# Activate the virtual environment
44
47
source .venv/bin/activate
45
48
```
@@ -50,6 +53,7 @@ source .venv/bin/activate
50
53
51
54
If you want to install the development versions, you can do so with:
This provides, among other things, a play button in the top right corner of your editor that will run your Shiny app.
98
110
99
-
### Visual Studio Code
111
+
100
112
101
-
We recommend installing the [Python][vscode-python] and [Shiny][vscode-shiny] extensions for [Visual Studio Code][vscode]. This provides, among other things, a play button in the top right corner of your editor that will run your Shiny app.
113
+
## Visual Studio Code
114
+
115
+
For for [Visual Studio Code][vscode],
116
+
you will need the [Python][vscode-python] and [Shiny][vscode-shiny] extensions.
102
117
103
118
If [type checking is important](https://john-tucker.medium.com/type-checking-python-306ad8339da1) to you, in addition to installing the [Python VSCode extension][vscode-python], you may want to do some additional configuration for a smooth experience with types in Shiny. See the tip below for more details.
104
119
@@ -118,7 +133,7 @@ We recommend the following settings in your project's `.vscode/settings.json` fi
118
133
119
134
or alternatively, if your project keeps these settings in `pyrightconfig.json`:
120
135
121
-
```default
136
+
```json
122
137
{
123
138
"typeCheckingMode": "basic",
124
139
"reportUnusedFunction": "none",
@@ -127,7 +142,7 @@ or alternatively, if your project keeps these settings in `pyrightconfig.json`:
127
142
128
143
The `basic` type checking mode will flag many potential problems in your code, but it does require an understanding of type hints in Python. This is the mode that is used by the [Shinylive](https://shinylive.io) examples editor. If you want to make even greater use of type checking, you can use `strict` mode:
129
144
130
-
```default
145
+
```json
131
146
"python.analysis.typeCheckingMode": "strict"
132
147
```
133
148
@@ -137,60 +152,14 @@ In the above configuration, we also disable the `reportUnusedFunction` diagnosti
137
152
138
153
You can also modify these settings on a per-file basis with comments at the top of the file. For example, you might have something like this at the top of your `app.py`:
139
154
140
-
```default
155
+
```python
141
156
# pyright: strict
142
157
# pyright: reportUnusedFunction=false
143
158
```
144
159
145
160
A full list of configuration settings for Pyright/Pylance is available [here](https://github.com/microsoft/pyright/blob/main/docs/configuration.md).
The best way to create a new Shiny app is with the `shiny create` command line interface (CLI). This command asks you a series of questions about what kind of app you want to create, and then provides all the boilerplate code you need to get started with a working app.
156
-
157
-
```bash
158
-
shiny create
159
-
```
160
-
161
-
{class="img-shadow"}
162
-
163
-
::: callout-tip
164
-
### Copy/paste examples
165
-
166
-
If you find an example on this site that you want to run/edit locally, you can use `shiny create --template basic-app -m express` to get a basic app template, and then copy/paste the code from the example into the template.
167
-
:::
168
-
169
-
170
-
## Run
171
-
172
-
Shiny apps can be launched from VSCode or the command line (via `shiny run`).
173
-
174
-
### VS Code
175
-
176
-
The best way to run (and develop) Shiny apps is in [Visual Studio Code][vscode] with the [Shiny extension][vscode-shiny]. When a Shiny `app.py` file is being edited, the default behavior of the Run button (circled in red in the screenshot below) becomes "Run Shiny App".
177
-
178
-
179
-
180
-
This launches a Python process in a dedicated terminal instance, and a captive web browser. This lets you test your app without leaving your editor, and whenever you make changes to your app's source, the preview will update. To preview your app in a full browser, click the icon to the right of the URL bar to launch the app in an external browser.
181
-
182
-
Next to the Run button is a dropdown menu that lets you "Debug Shiny App". This launches the app in debug mode, which lets you set breakpoints and step through your code. See the [debugging](debug.qmd) section for more information.
183
-
184
-
### Command line
185
-
186
-
To run a Shiny app from the command line, use the `shiny run` command. This command takes a single argument, the path to the app's entry point. For example, if your app's entry point is `app.py` in the directory `./app_dir`, you can run it like this:
187
-
188
-
```bash
189
-
shiny run --reload --launch-browser app_dir/app.py
190
-
```
191
-
192
-
This should start your app and also automatically launch a web browser.
193
-
194
-
The `--reload` flag means that file changes in the current directory tree will cause the Python process to restart and the browser to reload. Update and save changes to `app.py` and then wait a moment for the changes to appear in the browser.
195
-
196
-
With these two `shiny` commands, you now have a project that you can run in your terminal. You can use any text editor or Python IDE to write Shiny apps, but we've taken special care to ensure a smooth workflow for [Visual Studio Code][vscode]. The next section will help you set up VS Code for Shiny for Python.
0 commit comments