Why do we push the building app and not only the html files on netlify?

I have a question that might be stupid so I post it here…

I followed several tutorials on static cms that are deployed on netlify, but I have a pending question. With Pelican or Nikola, we have an output folder in which we generate our html site when we build it. We could imagine a workflow where we push only the output without further configuration and we would have a working site.
However, the actual workflow is to push all the packages and dependency, rebuilding the output that is then somehow published.

As a beginner, I see netlify as a bit of a black box, and I don’t understand why we have to go through all the troubleshooting of that complex workflow ?

I’m a bit inexperienced as well but I imagine someone else will come along and add or correct this.

You usually don’t push the packages themselves, you push a list of the packages you’ve used package.json along with some other files and a package manager like Yarn or NPM looks at this file and says okay we need to grab these packages with these specific versions and download install them.

Then whatever framework or website builder you’re using comes along and bundles all of this and I think Netlify replaces the paths (links) to the resources in the built out html.

So why?

  1. Reproducibility - Usually Netlify links to a Version Control System like GitHub. When you’re working in a team you want everything to be consistent across everyone’s machines. By having a list of packages that are pulled directly from source and config files that dictate how packages should behave you enable everyone to have the same experience. This is especially useful for debugging! Sometimes even the Netlify team will clone your repository and spin up your project on their end to help you identify errors. This wouldn’t be possible if all your code was on your machine and specific to your machine.

  2. Structure - Machines will read and execute code no matter what we throw at them (though they won’t necessarily always do what we want). However to keep code organized frameworks or site builders will usually have a folder structure that defines what should go where. This helps you to avoid spaghetti code and it also helps other developers help you if ever there’s a problem

  3. Performance - Once your site crosses a certain level of complexity, performance becomes an issue. That’s when tools like Webpack, Rollup and PurgeCSS will be great to use to help you do code splitting, lazy loading and stripping unneccessary bytes of code from your site. Doing this manually would be an absolute chore.

  4. Reliability - Netlify and GitHub form part of a CI/CD pipeline. This allows you to write tests using things like Jest and Mocha, that run every time you push changes to your repository. Imagine testing every bit of code in your whole project every time you made a change to it. Automated testing really helps you here and if something fails you know exactly where to look. You don’t (hopefully) have to sit down and wonder where it all went wrong.

So in summary

You absolute do not have to. You can write your website in HTML, CSS and JS and drag and drop the folder into Netlify and just serve that (that’s probably advisable for light websites anyway). Even if you were building a large site you could run the build commands on your machine and just upload the dist folder. Netlify just simplifies the process, helps you automate the workflow and allows you to easily collaborate with members on your team.


this is a fantastic response @simeon9696! I couldn’t have said it better!

@nidupb - does that help make things more clear?

we made Netlify as flexible as possible in order to accommodate many different approaches to building - that’s why you can drag n drop deploy html, build on deploy with a CI/CD pipeline, or even use a command line tool!

In time as you gain experience, you’ll get a feel for which way of deploying is the most efficient for you. The best build approach is the one that makes sense to you and that you’ll use, after all!

1 Like

yes, thanks for your help @simeon9696 !

1 Like

@nidupb Welcome to the Netlify community.

I’m with you. I don’t like trusting important tasks to black boxes. I think the main reason things are done this way is so that teams can work on the same project via GitHub (etc.), or you can work on the same project from various devices, locations, etc., also via GitHub. The secondary benefit is that building the full site usually more than duplicates the space requirements on your drive(s) – including your backups.

However, there is no law that says you cannot upload / post only the built files yourself. In fact, that’s what I do and it works great.

The caveat is that you may be “limited” to drag-n-drop updates. They run like a scalded cat, but you do have to ZIP up your project, open the Netlify dashboard for the site, and so on, whereas with GitHub integration you simply push your updates and they appear on Netlify.

Maybe someone brighter than me can tell you how to incorporate GitHub with your build folder only, but my understanding of the way that Pelican and Nikola and the others work is that they can (at least sometimes) clear out the build folder, which could mean clearing out the .git directory, which would mean losing that project’s connection to GitHub … and that would be a pain in the neck if it happened often.

However, if you want to use a build tool to generate your site, and you don’t mind the steps involved with drag-n-drop, you’ll be astonished at how quickly Netlify deploys your project.


Ik this is old but you mentioned wanting to incorporate GitHub and Netlify with your dist folder only. I think you could accomplish this by using branch deploys. So your master/main would be the dist folder contents only (make sure there’s and index.html at the root) and the other branches would be your dev environments.

Then you can set-up a netlify.toml with custom build commands. In my one below, the build command is for the branch maps is just true. Netlify would see this and not do anything, just deploy the files on that branch. It currently works really well for a site of mine.

 command="npm run generate --modern"

  publish = "dist"

  publish = "dist"

  command = "true"

You need to clear out any build commands on the webGUI for this to work. You can see how we got here on this question