/app/src/client VS /app/src/server?
tldr; I'm struggling to understand what files (if any) should be in the /server vs the /client directory. Best practices? Security implications?
Hi there,
This is going to sound super newby - excuse my ignorance. I'm not a software developer by trade, I'm just the type who gets ideas, rolls up his sleeves, and learns what's necessary as I go along. WASP seemed like a great fit some someone with a beginner level understanding to help me rapid prototype and get an MVP, so here I am, I've learned a lot along the way but lack a lot of the fundamentals (obviously) of full stack development.
I've been building a SaaS platform over the past four months. I started building it based on the OpenSaaS template back in November, and have only two files in my /sever folder.
dbSeeds.ts and a serverSetup.ts (which basically just does this):
middlewareConfig.set('express.json', bodyParser.json({ limit: '50mb' }));
Currently, nearly everything I've built is in my /client directory including operations.ts etc.
I've successfully deployed FE+BE+DB via Google Cloud with no errors - I'm not totally sure what the implications are of having everything in my /client directory.
How does the wasp framework actually know what files are part of the backend build & deployment vs frontend build & deployment? Are there security implications or major red flags by having everything in the /client directory? Am I looking at this totally wrong?
12 Replies
Hi @G35x. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
Thank you for your question about Wasp's project structure. I understand your confusion, especially since you started with an older version of Wasp. Let me clarify the current situation and best practices for you.
As of Wasp 0.12.0, released in early 2024, the project structure has changed significantly. The strict separation between
/src/client and /src/server directories is no longer required or recommended. Here's what you need to know:
1. New Project Structure:
Wasp now allows you to organize your code however you think is best, as long as it's inside the src directory. There's no need to separate client files from server files into different directories.
Migration from 0.11.X to 0.12.X explains:
"The server/client code separation is no longer necessary. You can now organize your code however you want, as long as it's inside the src directory."
2. File Organization:
While you can organize files as you prefer, the Wasp team recommends organizing by features for larger projects. This allows for better code organization and maintainability.
Tutorial: Project Structure mentions:
"We'd normally recommend organizing code by features (i.e., vertically). However, since this tutorial contains only a handful of files, there's no need for fancy organization."
3. Imports in main.wasp:
All external imports in your Wasp file must now have paths starting with @src (e.g., import foo from '@src/bar.js') where @src refers to the src directory in your project root.
4. Security Implications:
There are no inherent security implications of having all your code in one directory. Wasp handles the separation of client and server code during the build process.
5. Backend vs Frontend:
Wasp determines which code is for the backend and which is for the frontend based on how you use it in your main.wasp file and the imports in your code. It's not determined by the directory structure anymore.
Given that you started with an older template, I would recommend updating your project structure to align with the new Wasp recommendations. This might involve:
1. Moving all your code into the src directory.
2. Organizing by features if your project is large enough to warrant it.
3. Updating your main.wasp file to use @src imports.
Remember, there's no need to strictly separate client and server code anymore. Wasp will handle that separation during the build process based on how you use the code in your main.wasp file and your imports.
If you want to distinguish between client and server code for your own organization, you can use naming conventions or comments, but it's not required by Wasp.
Github Issue: Can we help users distinguish their client and server JS files discusses some ideas for this, such as using file extensions like .server.js or .client.js, or using comments like /* use server */ or /* use client */ at the top of files.
I hope this clarifies things for you. The main takeaway is that with the current version of Wasp, you have much more flexibility in how you organize your code, and you don't need to worry about strict client/server separation in your project structure.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------
Sorry @G35x, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist:
Perhaps try again in 15mins?As the bot suggested, you’re free to organise your code within the
src directory as you please without any security or technical implications.
However, your current setup doesn’t sound particularly intuitive. Imagine if you had a collaborator join the project; they wouldn’t expect to find server-side code like operations.ts in the client directory. If you are going to retain the original client and server directories, then you should organise your code accordingly.
I personally prefer and use the feature-based arrangement as mentioned by the bot, but it really is up to you to choose a structure that best suits the scale of your project and your personal coding style.Wohooo @genyus, you just became a Waspeteer level 7!
Hey @G35x, nice to see you again!
It's always a pleasure reading your questions. They're always very detailed and thought through, so no need to apologize. Far from it!
Anyway, to answer this one:
- Older versions of Wasp required users to explicitly split their server and client files
- Sicne 0.12.0, Wasp no longer poses this limitation. See the old migration guide for details: https://wasp.sh/docs/migration-guides/migrate-from-0-11-to-0-12#new-project-structure
What we recommend now is:
- Organize your code by features/vertically. Group things based on what they are in the domain: account, tasks, payments.... For example, the account folder could contain files with react components for the account page, as well as backend operations for the account.
- Don't organize your project by functionality/horizontally. So, don't group stuff simply because they're all pages, or that they're all actions...
In short: you can delete the
client and server dir and organize code however you want. I recommend moving the two files you have in server into appropriate places in the client and then moving everything from the client into src, before finally deleting client.
Why organize code by features?
The rules of thumb are:
The top level directory structure of a project should clearly state what the application does. It should be saying "this is an application for users and their tasks" and not "this is a Wasp web application"And
If my boss [in your case, you] asked me to delete all of the code for feature foo, how hard would that be?If you are more bullish on your features and cannot imagine a world where you'd ever want you to delete anything, feel free to change the question to:
When <insert Fortune 500 company> inevitably acquires my startup, how easy will it be for me to copy/paste modules into their monorepo?Answering some questions
How does the wasp framework actually know what files are part of the backend build & deployment vs frontend build & deployment?It figures it out by following the tree of imports. For example, let's look at the client. It starts by including your pages, then including all the imports those pages need, then including all the imports those imports need, and so on... You can in theory have a
utils.ts file that' used by both frontend and backend code.
To learn more about this, google "Tree shaking"
Are there security implications or major red flags by having everything in the /client directory?As long as you don't import anything you didn't want into the client code by accident, you should be fine. But we should definitely make this more robust, so thanks for pointing it out!
Am I looking at this totally wrong?Not at all! Those are great questions. Keep up the great work and let me know if I can help with anything else 🙂
@genyus Really appreciate the feedback! I've been organizing by feature so far and trying my best not to abstract the codebase too much.
Deciding what is really a standalone feature vs what is a sub-feature (and won't be used in another domain) isn't always easy but I think I'm finally finding a rhythm.
I will typically build out a large feature, then refactor, then finally refine the UI/UX before moving on. Main goals of my refactors are to eliminate redundancy, create common utilities, and generally keeping files under 300 lines (within reason).
The main issue is, I was worried I'm exposing something sensitive within the client that should be part of the server. Thankfully, the WASP team is smarter than I am and thought of that already haha!
from what I've gathered, grouping the operations.ts files inside of the directory for any given feature isn't a cardinal sin and may even lend to easier maintenance in the future.
@sodic this is such a goldmine of information for me in my situation. I appreciate you taking the time to understand where I am in my understanding and give me threads to pull on and learn from.
Not only did you give me the "WHAT" in what I was looking for, but the "WHY".
Tree shaking is on my to-do list today to dig into, and I'll need to figure out how to know what not to import into the client code.
The project I'm working on is what some of my developer friends have called "ambitious".. to put it lightly. And it very well may deal with sensitive (but non-regulated) user data so I really want to take my time and understand this fully.
Before I launch I plan to do some solo pentesting before I contract out an audit to a 3p, so if you have any resources or any other "threads" I can pull on related to secure coding practices I'd be very thankful!
Wohooo @G35x, you just became a Waspeteer level 3!
from what I've gathered, grouping the operations.ts files inside of the directory for any given feature isn't a cardinal sin and may even lend to easier maintenance in the future.If it helps, the following how I organised my current project. This is an entirely opinionated structure, so feel free to ignore or adapt as you see fit, but hopefully it might give you one example of the many ways you can organise your codebase:
Very glad you found it useful!
Thanks for sharing @genyus, this is great!
@genyus this was actually extremely helpful to see! Thank you for sharing.. Do you use a VS plugin to make a file tree? How'd you generate this?
Sry for late reply, been working on a DSP plugin. Working with raw C++ really makes me appreciate how great/easy to use WASP is 🥹
I actually generated it with ChatGPT sometime ago to include in my .cursorrules file. This wasn’t generated from an existing directory structure, I just prompted it with the structure I wanted
Smart adding this to curssorrules. This might solve a big problem I've been having with Cursor since that update a couple weeks ago.. it's been taking some creative liberties and creating files in erroneous locations so this might tighten up the performance
Yep, I had the same issues when I first started the project a couple months ago, so I don’t think it’s even a new problem. Defining the structure should make a noticeable difference