Add support for debugging TS apps (encoredev#1281)

cli/cmd/encore/run.go

@@ -46,6 +46,9 @@ func init() {
 		Args:  cobra.NoArgs,
 		Run: func(cmd *cobra.Command, args []string) {
 			appRoot, wd := determineAppRoot()
+			if !cmd.Flag("watch").Changed && debug {
+				watch = false
+			}
 			runApp(appRoot, wd)
 		},
 	}

cli/cmd/tsbundler-encore/main.go

@@ -101,7 +101,7 @@ func main() {
 		LogLevel:  api.LogLevelWarning - api.LogLevel(logLevel),
 		Banner:    map[string]string{"js": banner},
 		Charset:   api.CharsetUTF8,
-		Sourcemap: api.SourceMapExternal,
+		Sourcemap: api.SourceMapLinked,
 		Packages:  api.PackagesExternal,
 		Plugins:   []api.Plugin{
 			// rewritePlugin,

docs/menu.cue

@@ -498,6 +498,11 @@
 		  text: "Logging"
 		  path: "/ts/develop/logging"
 		  file: "ts/develop/logging"
+		}, {
+		  kind: "basic"
+		  text: "Debugging"
+		  path: "/ts/develop/debug"
+		  file: "ts/develop/debug"
 		}]
 	},{
 		kind: "section"

docs/observability/logging.md

@@ -3,6 +3,7 @@ seotitle: Use structured logging to understand your application
 seodesc: Learn how to use structured logging, a combination of free-form log messages and type-safe key-value pairs, to understand your backend application's behavior.
 title: Logging
 subtitle: Structured logging helps you understand your application
+lang: go
 infobox: {
   title: "Structured Logging",
   import: "encore.dev/rlog",

docs/ts/develop/debug.md

@@ -0,0 +1,56 @@
+---
+seotitle: How to debug your TS backend application
+seodesc: Learn how to debug your TS backend application using Encore.
+title: Debug with your IDE
+lang: ts
+---
+
+Encore makes it easy to debug your application using your favorite IDE. 
+
+## Enable debugging mode
+Next, run your Encore application with `encore run --debug`. This will cause Encore to run your app with the `--inspect-brk` flag, which will pause your application until a debugger is attached. Encore will print the URL to the terminal, which you will use to attach your debugger:
+
+```shell
+$ encore run --debug
+  Your API is running at:     http://127.0.0.1:4000
+  Development Dashboard URL:  http://localhost:9400/ai-chat-ts-qhwi
+  Process ID:                 38965
+
+Debugger listening on ws://127.0.0.1:9229/473dd95f-e71e-4bf2-9eda-6132dd0d6ae3
+```
+
+(Your process id and url will differ).
+
+## Attach your debugger
+When your Encore application is running, it’s time to attach the debugger. The instructions differ depending on how you would like to debug. If instructions for your editor aren’t listed below, consult your editor for information on how to attach a debugger to a running process.
+
+### Visual Studio Code
+To debug with VS Code you must first add a debug configuration. Press `Run -> Add Configuration`, choose `Node.js -> Attach`. The generated config should look something like this:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Attach",
+      "port": 9229,
+      "request": "attach",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "type": "node"
+    }
+  ]
+}
+```
+
+Next, open the **Run and Debug** menu in the toolbar on the left, select Attach (the configuration you just created), and then press the green arrow.
+
+That’s it! You should be able to set breakpoints and have the Encore application pause when they’re hit like you would expect.
+
+## WebStorm
+To debug with WebStorm (or any other JetBrains IDE), you must first configure a Node.js Attach configuration. Press `Run -> Edit Configurations`, click the `+` button, and choose `Attach to Node.js/Chrome`. Give it a name and hit `OK`. 
+Now select the configuration you just created and press the green bug.
+
+That's it. You should be able to set breakpoints and have the Encore application pause when they’re hit like you would expect.
+

docs/ts/develop/logging.md

@@ -3,6 +3,7 @@ seotitle: Use structured logging to understand your application
 seodesc: Learn how to use structured logging, a combination of free-form log messages and type-safe key-value pairs, to understand your backend application's behavior.
 title: Logging
 subtitle: Structured logging helps you understand your application
+lang: ts
 infobox: {
   title: "Structured Logging",
   import: "encore.dev/log",

tsparser/src/bin/tsparser-encore.rs

@@ -149,6 +149,7 @@ fn main() -> Result<()> {
                                 working_dir: &cwd,
                                 desc: parse,
                                 use_local_runtime: input.use_local_runtime,
+                                debug: input.debug,
                             };
 
                             log::info!("starting compile");
@@ -311,6 +312,7 @@ struct PrepareInput {
 struct CompileInput {
     runtime_version: String,
     use_local_runtime: bool,
+    debug: bool,
 }
 
 #[derive(Deserialize, Debug)]

tsparser/src/builder/compile.rs

@@ -22,6 +22,7 @@ pub struct CompileParams<'a> {
     pub working_dir: &'a Path,
     pub desc: &'a AppDesc,
     pub use_local_runtime: bool,
+    pub debug: bool,
 }
 
 #[derive(Serialize, Debug)]
@@ -36,6 +37,7 @@ pub struct JSBuildOutput {
     pub artifact_dir: PathBuf,
     pub entrypoints: Vec<Entrypoint>,
     pub uses_local_runtime: bool,
+    pub debug: bool,
 }
 
 #[derive(Serialize, Debug)]
@@ -148,6 +150,7 @@ impl Builder<'_> {
             artifact_dir: build_dir.as_path(),
             runtime_version: params.runtime_version,
             cwd: params.app.root.as_path(),
+            debug: params.debug,
             inputs,
         })?;
 
@@ -158,6 +161,7 @@ impl Builder<'_> {
                 artifact_dir: build_dir,
                 entrypoints: result.entrypoints,
                 uses_local_runtime: params.use_local_runtime,
+                debug: params.debug,
             }],
         })
     }

tsparser/src/builder/transpiler.rs

@@ -42,6 +42,9 @@ pub struct TranspileParams<'a> {
 
     /// The services and gateways to transpile.
     pub inputs: Vec<Input>,
+
+    // If we should transpile for debug
+    pub debug: bool,
 }
 
 pub struct TranspileResult {
@@ -112,6 +115,10 @@ impl OutputTranspiler for EsbuildCompiler<'_> {
                     "--preserve-symlinks".into(),
                 ];
 
+                if p.debug {
+                    command.push("--inspect-brk".to_string())
+                }
+
                 // Finally we want to add the path to the bundled app
                 command.push(entrypoint_path.clone());
 

v2/tsbuilder/tsbuilder.go

@@ -193,6 +193,7 @@ func (i *BuilderImpl) Parse(ctx context.Context, p builder.ParseParams) (*builde
 type compileInput struct {
 	RuntimeVersion  string `json:"runtime_version"`
 	UseLocalRuntime bool   `json:"use_local_runtime"`
+	Debug           bool   `json:"debug"`
 }
 
 func (i *BuilderImpl) Compile(ctx context.Context, p builder.CompileParams) (*builder.CompileResult, error) {
@@ -201,6 +202,7 @@ func (i *BuilderImpl) Compile(ctx context.Context, p builder.CompileParams) (*bu
 	input, _ := json.Marshal(compileInput{
 		RuntimeVersion:  version.Version,
 		UseLocalRuntime: p.Build.UseLocalJSRuntime,
+		Debug:           p.Build.Debug,
 	})
 
 	_, _ = data.stdin.Write([]byte("compile\n"))