Create `wasp build start` command #2796

cprecioso · 2025-05-26T12:10:44Z

Resolves #1883

Implements a new wasp build start command.
It will take the output from wasp build, build the client, the server, and run them both.

The logic is consistent with wasp-app-runner, except we don't run the SMTP server or the DB.

Nothing is excessively surprising, except maybe the creation of a JobExcept type to make working with the jobs easier. This might later grow into a full orchestration utility if we want.

…-runs-output-of-wasp-build

cloudflare-workers-and-pages · 2025-06-03T11:43:07Z

Deploying wasp-docs-on-main with Cloudflare Pages

Latest commit:	`c09269c`
Status:	✅ Deploy successful!
Preview URL:	https://dfa20b17.wasp-docs-on-main.pages.dev
Branch Preview URL:	https://1883-implement-wasp-build-st.wasp-docs-on-main.pages.dev

View logs

…-runs-output-of-wasp-build

Martinsos · 2025-06-05T08:32:48Z

Did a round of pair reviewing with Carlos on this one, will review it again once it is out of draft stage.

…mksmyl

…-command-that-runs-output-of-wasp-build

infomiho

I left some suggestions

waspc/cli/src/Wasp/Cli/Command/BuildStart.hs

infomiho · 2025-07-17T08:31:56Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/ArgumentsParser.hs

+    makeEnvironmentVariableParser prefix =
+      Opt.strOption $
+        Opt.long (prefix <> "-env")
+          <> Opt.short (head prefix)


Nitpick: maybe we drop the short option since it might cause some conflicts (now s and c are taken, who knows if in the future we want to add new long options e.g. secret-sauce which would result in another s option jk but you get my point)

Yeah I know, but if we want to add multiple envs, wasp build start --server-env JWT_SECRET=my-secret --server-env GOOGLE_CLIENT_ID=my-client-id --server-env GOOGLE_CLIENT_SECRET=my-client-secret etc is going to get old very quickly...

Hey, I'm not against short hand properties but in the dynamic way you generate them from the first char, I felt like there is some danger in stepping on toes :D Maybe the answer is to be explicit and have longOptionName and shortOptionName as input?

Ahh got it, makes sense!

waspc/cli/src/Wasp/Cli/Command/BuildStart/Client.hs

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

waspc/cli/src/Wasp/Cli/Command/BuildStart/Server.hs

infomiho · 2025-07-17T08:52:12Z

waspc/src/Wasp/Env.hs

-parseDotEnvFile :: Path' Abs (File ()) -> IO [EnvVar]
-parseDotEnvFile envFile =
-  Dotenv.parseFile (fromAbsFile envFile)
+parseDotEnvFilePath :: FilePath -> IO [EnvVar]


We are losing type safety here e.g. FilePath is much less defined than Path' Abs (File ()). Can we avoid doing this and parse the user provided file path? For example, we assume it will be a relative file path which we can then combine with the Wasp project dir into an absolute file path?

I spent some time fighting with SP but I don't think I was able to express what I wanted. The args can both be given as an absolute path, or as a relative path to cwd. How can I parse that with SP?

I'd say you can parse the input and get an absolute path always:

if it's already absolute, great, parsing succeeded (parseAbsFile)

if it's not, construct an absolute path by combining the provided path and the Wasp project

This way, we validated input and we have strong guarantees about the paths we are dealing with. Do you want to give it a go?

infomiho · 2025-07-17T08:56:34Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Server.hs

+
+    extraEnvParamsFromConfig =
+      Config.serverEnvironmentVariables config
+        >>= \envVar -> ["--env", envVar]


We are not parsing the user provided server env variables here. We are doing much more with the client env vars e.g. parsing them into EnvVar and then nubing them. I'd like us to do the same here so we can be sure that we are not passing malformed input to the docker command.

We coule maybeparse the env vars at the beginning into EnvVar format which we can then show envVar here. That would make sense, because we don't need a list of strings in our config, but a list of EnvVar values.

We are doing much more with the client env vars

Yep, because we need to construct the env for the client manually. but here in docker we can just pass both as arguments, so I opted to skip the complex processing (esp. since Docker will just do it again).

Especially, converting to EnvVar ((String, String)), seems a bit pointless as I'm going to immediately convert them back to NAME=VALUE (because that's how docker expects it); plus if I do that I don't allow the passthrough syntax from Docker (-e JUST_THE_NAME).

Especially, converting to EnvVar ((String, String)), seems a bit pointless as I'm going to immediately convert them back to NAME=VALUE

The fact it passes from String -> EnvVar means that it is in a valid format and we can safely continue using the values. I think it's worthwhile doing even if we convert it right away.

plus if I do that I don't allow the passthrough syntax from Docker

Uu, this was unexpected, to me it feels like a bug because or command is not defined like that: https://github.com/wasp-lang/wasp/pull/2796/files#diff-4a6575b2b3839d30a9c37d2062e42b84eadb760bd7cef15b6ca264dfeb0f12ffR34

This is an extra argument for doing it - strings can be anything and we are letting Docker decide what the raw value means, instead of handling all the cases and making strongly typed programs.

Oki, will do

…-command-that-runs-output-of-wasp-build

…-runs-output-of-wasp-build

cprecioso

@infomiho ready

cprecioso · 2025-07-18T13:25:14Z

waspc/cli/src/Wasp/Cli/Util/Common.hs

I put this in a new file because I don't know really where else to put it, it didn't seem fine to tuck it into any other.

cprecioso · 2025-07-18T13:26:06Z

waspc/cli/src/Wasp/Cli/Util/EnvVarArgument.hs

+
+fromFilePath :: FilePath -> Either String EnvVarFileArgument
+fromFilePath str =
+  Path.parseSomeFile str


For checking if it is Abs or Rel, in the end I used the parseSomeFile fn from the Path package, seeing that StrongPath also has utilities to convert from it

cprecioso · 2025-07-18T13:28:52Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

Wdyt about this solution? Moved all the environment variable calculation to the config creationg, so we can just pass an [EnvVar] around, and not have 4 different but very similar properties.

And split the constructor into two parts, one initial one and another where we put the envs, as that part has to be IO.

cprecioso · 2025-07-18T13:29:50Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

+forceEnvVarsCommand :: [EnvVar] -> [EnvVar] -> Command [EnvVar]
+forceEnvVarsCommand forced existing =
+  case forceEnvVars forced existing of
+    Left duplicateNames ->
+      throwError $
+        CommandError "Duplicate environment variables" $
+          ("The following environment variables will be overwritten by Wasp and should be removed: " <>) $
+            intercalate ", " duplicateNames
+    Right combined -> return combined


If a user passes an environment variable that we override, they might get confused about why we're not using their value. So we explicitly tell them we're doing it and terminate.

…-runs-output-of-wasp-build

infomiho

Left some comments, mostly focusing on Config because I felt we could maybe organise the code to be easier to follow along. Let me know what you think, I've given you what I came up with, don't feel like you need to use it as-is.

infomiho · 2025-07-22T09:17:28Z

waspc/ChangeLog.md

+
+### 🎉 New Features
+
+- New command: `wasp build start`. It allows you to run your built Wasp app as it would run in your production server. Useful for testing your production build locally, and making sure of passing the correct environment variables. [#2796](https://github.com/wasp-lang/wasp/pull/2796)


Is the command "making sure of passing the correct environment variables" or the user is doing that? I know it's the changelog but I'd maybe make it more clear what you mean.

infomiho · 2025-07-22T09:29:08Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

+
+makeBuildStartConfig :: AppSpec -> BuildStartArgs -> SP.Path' SP.Abs (SP.Dir WaspProjectDir) -> Command BuildStartConfig
+makeBuildStartConfig appSpec args projectDir = do
+  let config = makeBuildStartConfigWithoutEnvVars appSpec projectDir


I'm afraid this half completed object creation - it means with might accidentally use it somewhere at some point in the future.

I'd like to see us construct the full object from the start. Why can't we construct the object with all the variables inside?

return makeBuildStartConfig appSpec projectDir serverEnvVars clientEnvVars

I've played around with it and came up with this:

makeBuildStartConfig :: AppSpec -> BuildStartArgs -> SP.Path' SP.Abs (SP.Dir WaspProjectDir) -> Command BuildStartConfig makeBuildStartConfig appSpec args projectDir = do let waspServerEnvVars = [ (Server.clientUrlEnvVarName, show clientPort), (Server.serverUrlEnvVarName, serverUrl') ] userServerEnvVars <- liftIO $ combineEnvVarsWithEnvFiles (Args.serverEnvironmentVariables args) (Args.serverEnvironmentFiles args) serverEnvVars' <- mergeEnvVarsCommand waspServerEnvVars userServerEnvVars let waspClientEnvVars = [(WebApp.serverUrlEnvVarName, serverUrl')] userClientEnvVars <- liftIO $ combineEnvVarsWithEnvFiles (Args.clientEnvironmentVariables args) (Args.clientEnvironmentFiles args) clientEnvVars' <- mergeEnvVarsCommand waspClientEnvVars userClientEnvVars return $ BuildStartConfig { appUniqueId = appUniqueId', buildDir = buildDir', clientPortAndUrl = (clientPort, clientUrl), serverEnvVars = serverEnvVars', clientEnvVars = clientEnvVars', serverUrl = serverUrl' } where buildDir' = projectDir </> dotWaspDirInWaspProjectDir </> buildDirInDotWaspDir appUniqueId' = makeAppUniqueId projectDir appName (appName, _) = ASV.getApp appSpec -- This assumes that `getDefaultDevClientUrl` uses `defaultClientPort` internally. -- If that changes, we also need to change this. clientPort = defaultClientPort clientUrl = getDefaultDevClientUrl appSpec serverUrl' = defaultDevServerUrl

infomiho · 2025-07-22T09:31:38Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

+    -- This assumes that `getDefaultDevClientUrl` uses `defaultClientPort` internally.
+    -- If that changes, we also need to change this.
+    clientPort = defaultClientPort
+    clientUrl = getDefaultDevClientUrl appSpec


A rewrite I'd suggest is introducing a ClientUrl data type that hold both values. And we'd keep this in the `Wasp.Generator.WebAppGenerator.Common

I know it's out of scope for this PR but I feel like the tuple is not the right data structure, accessing the port with fst feels unreadable and error-prone to me. We maybe should address it in the future.

infomiho · 2025-07-22T09:37:58Z

waspc/cli/src/Wasp/Cli/Util/Common.hs

@@ -0,0 +1,15 @@
+module Wasp.Cli.Util.Common


This feels very generic Util.Common - can we do something better? We already have Wasp.Util.IO for file/directory operations. Maybe this can go under that module e.g. Wasp.Util.IO.WorkingDirectory

infomiho · 2025-07-22T09:39:32Z

waspc/cli/src/Wasp/Cli/Util/EnvVarArgument.hs

+envVarFromString :: String -> Either String EnvVar
+envVarFromString var =
+  case break (== '=') var of
+    ([], _) -> failure
+    (name, '=' : value) -> Right (name, value)
+    _ -> failure
+  where
+    failure = Left $ "Environment variable must be in the format NAME=VALUE: " ++ var


Unit tests for this would be good, just to cover the expected failure scenarios.

infomiho · 2025-07-22T09:41:39Z

waspc/cli/src/Wasp/Cli/Util/EnvVarArgument.hs

+data EnvVarFileArgument
+  = AbsoluteEnvVarFile (Path' Abs (File ()))
+  | RelativeEnvVarFile (Path' (Rel WorkingDir) (File ()))
+
+readEnvVarFile :: EnvVarFileArgument -> IO [EnvVar]
+readEnvVarFile arg = toStrongPath arg >>= parseDotEnvFile
+  where
+    toStrongPath :: EnvVarFileArgument -> IO (Path' Abs (File ()))
+    toStrongPath (AbsoluteEnvVarFile path) = return path
+    toStrongPath (RelativeEnvVarFile path) = (</> path) <$> getWorkingDir


Great change 👍

infomiho · 2025-07-22T12:02:21Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

+
+  serverEnvVars' <-
+    readAndForceEnvVars
+      [ (Server.clientUrlEnvVarName, show $ fst $ clientPortAndUrl config),


clientUrlEnvVarName expects the URL, but we are giving it the port here

infomiho · 2025-07-22T12:14:36Z

waspc/src/Wasp/Env.hs

+forceEnvVars :: [EnvVar] -> [EnvVar] -> Either [String] [EnvVar]
+forceEnvVars forced existing =
+  if null duplicateNames
+    then Right (forced <> existing)
+    else Left duplicateNames
+  where
+    duplicateNames = filter (`Set.member` forcedNames) existingNames
+    forcedNames = Set.fromList $ map fst forced
+    existingNames = map fst existing


I'd maybe make the function more generic, it's used to merge env vars while keeping an eye on duplicates.

This is what I came up with while playing with it:

mergeEnvVars :: [EnvVar] -> [EnvVar] -> Either [String] [EnvVar] mergeEnvVars envVars1 envVars2 = if null duplicateNames then Right (envVars1 <> envVars2) else Left duplicateNames where duplicateNames = filter (`Set.member` envVarNames1) envVarNames2 envVarNames1 = Set.fromList $ map fst envVars1 envVarNames2 = map fst envVars2

infomiho · 2025-07-22T12:16:45Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

+-- values we've hardcoded in the generator. In the future, we might want to make
+-- these configurable via the Wasp app spec or command line arguments.
+
+serverUrl :: BuildStartConfig -> String


I'd also move this to the config because this requires you to have config to get the serverUrl in the makeBuildStartConfig.

infomiho · 2025-07-22T12:19:01Z

waspc/cli/src/Wasp/Cli/Command/BuildStart/Config.hs

+readAndForceEnvVars :: [EnvVar] -> [EnvVar] -> [EnvVarFileArgument] -> Command [EnvVar]
+readAndForceEnvVars forced existing files = do
+  readVars <- liftIO $ readEnvVars existing files
+  forceEnvVarsCommand forced readVars
+
+readEnvVars :: [EnvVar] -> [EnvVarFileArgument] -> IO [EnvVar]
+readEnvVars pairs files = do
+  pairsFromFiles <- mapM readEnvVarFile files
+  let allEnvVars = pairs <> concat pairsFromFiles
+  return $ nubEnvVars allEnvVars
+
+forceEnvVarsCommand :: [EnvVar] -> [EnvVar] -> Command [EnvVar]
+forceEnvVarsCommand forced existing =
+  case forceEnvVars forced existing of
+    Left duplicateNames ->
+      throwError $
+        CommandError "Duplicate environment variables" $
+          ("The following environment variables will be overwritten by Wasp and should be removed: " <>) $
+            intercalate ", " duplicateNames
+    Right combined -> return combined


Something felt off while I was reading this code, like IO and pure code were intertwined and some of the concerns weren't separated in the cleanest way, I've played around with it like this:

mergeEnvVarsCommand :: [EnvVar] -> [EnvVar] -> Command [EnvVar] mergeEnvVarsCommand waspEnvVars userEnvVars = do case mergeEnvVars waspEnvVars userEnvVars of Left duplicateNames -> throwError $ CommandError "Duplicate environment variables" $ ("The following environment variables will be overwritten by Wasp and should be removed: " <>) $ intercalate ", " duplicateNames Right combinedEnvVars -> return combinedEnvVars combineEnvVarsWithEnvFiles :: [EnvVar] -> [EnvVarFileArgument] -> IO [EnvVar] combineEnvVarsWithEnvFiles pairs files = do pairsFromFiles <- mapM readEnvVarFile files let allEnvVars = pairs <> concat pairsFromFiles return $ nubEnvVars allEnvVars

You'll notice that now the IO and non-IO stuff is separate and you'll need to invoke two functions in the main fn:

let waspClientEnvVars = [(WebApp.serverUrlEnvVarName, serverUrl')] userClientEnvVars <- liftIO $ combineEnvVarsWithEnvFiles (Args.clientEnvironmentVariables args) (Args.clientEnvironmentFiles args) clientEnvVars' <- mergeEnvVarsCommand waspClientEnvVars userClientEnvVars

This felt easier to follow along: we have Wasp vars and user vars. User vars are computed from vars and files.

wip

3e05664

cprecioso self-assigned this May 26, 2025

cprecioso added 7 commits June 2, 2025 17:31

Use common abstractions

9ea053f

Remove build

e06a292

Remove unused imports

5e7c8c3

Fix

128f70e

Merge branch 'main' into 1883-implement-wasp-build-start-command-that…

ddc9a32

…-runs-output-of-wasp-build

Merge branch 'main' into 1883-implement-wasp-build-start-command-that…

5b57571

…-runs-output-of-wasp-build

Just learned about ExceptT

9e72db1

cprecioso added 8 commits June 3, 2025 15:44

Now it works!

5b44f5c

Merge branch 'main' into 1883-implement-wasp-build-start-command-that…

87734fc

…-runs-output-of-wasp-build

Allow dbExecuteTest to run without built .env files

9a2831b

Pass the error channel around for printing if needed

b1a4e97

Print Prisma output when there's an unknown error

30c4a7c

Allow requirement to be parametrized by folder

f262562

Merge better prisma

6d86658

Add checking DB connection

01ac717

cprecioso force-pushed the 1883-implement-wasp-build-start-command-that-runs-output-of-wasp-build branch from f269680 to 01ac717 Compare June 4, 2025 16:20

cprecioso mentioned this pull request Jun 4, 2025

Improve the DBConnectionEstablished Command Requirement #2820

Closed

cprecioso changed the base branch from main to cprecioso/push-yppoqwmksmyl June 5, 2025 07:15

Martinsos self-requested a review June 5, 2025 08:32

cprecioso added 7 commits June 5, 2025 14:41

Improve JobExcept abstraction

0b91a74

Correct

a35f5a6

Add Build dir check

af0772c

Remove workaround for interactive Prisma

df97486

Merge branch 'cprecioso/push-rmwtsrklmvrs' into cprecioso/push-yppoqw…

c326246

…mksmyl

Better env handling

fd4b9d5

Simple

80e43ed

Merge branch 'push-uuqynktmlxnr' into 1883-implement-wasp-build-start…

6c8b47a

…-command-that-runs-output-of-wasp-build

infomiho reviewed Jul 17, 2025

View reviewed changes

cprecioso added 8 commits July 17, 2025 16:52

Rename

2220f20

Remove from starter

8d1e5a5

Qualify AuthG

000c033

Merge branch 'push-uuqynktmlxnr' into 1883-implement-wasp-build-start…

316a97a

…-command-that-runs-output-of-wasp-build

Update

3f2db84

comments

d57b233

Comment

56ce5a7

Comments

399f664

infomiho self-requested a review July 17, 2025 16:43

Base automatically changed from push-uuqynktmlxnr to main July 17, 2025 20:46

cprecioso added 12 commits July 18, 2025 10:54

Merge branch 'main' into 1883-implement-wasp-build-start-command-that…

0ea6f52

…-runs-output-of-wasp-build

Merge branch 'main' into 1883-implement-wasp-build-start-command-that…

3c1ce25

…-runs-output-of-wasp-build

Comment

acb5b9e

Add comment

f4a892e

Always parse env vars

315a5b6

Parse env var files

f10fe23

Parse env var args when creating config

54e37d6

forceEnvVars impl

b75cb86

Force env vars in config

3ebeda6

Reorder

6ec1329

Reorder

5335604

Reorder

9a31194

cprecioso commented Jul 18, 2025

View reviewed changes

cprecioso added 4 commits July 18, 2025 15:31

Remove unneeded import

c38eb7f

Merge branch 'main' into 1883-implement-wasp-build-start-command-that…

00e6a5a

…-runs-output-of-wasp-build

Add changelog

67ff2e4

docs

c09269c

infomiho reviewed Jul 22, 2025

View reviewed changes


		### 🎉 New Features

		- New command: `wasp build start`. It allows you to run your built Wasp app as it would run in your production server. Useful for testing your production build locally, and making sure of passing the correct environment variables. [#2796](https://github.com/wasp-lang/wasp/pull/2796)

Uh oh!

Create wasp build start command #2796

Are you sure you want to change the base?

Create wasp build start command #2796

Uh oh!

Conversation

cprecioso commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-workers-and-pages bot commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wasp-docs-on-main with Cloudflare Pages

Uh oh!

Martinsos commented Jun 5, 2025

Uh oh!

infomiho left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cprecioso left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

infomiho left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Create `wasp build start` command #2796

Create `wasp build start` command #2796

cprecioso commented May 26, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Jun 3, 2025 •

edited

Loading