Jak uspořádat složku JavaScriptu pro větší projekty

Co je složka souborů JavaScriptu

Složka souborů JavaScriptu představuje základní organizační jednotku v každém webovém projektu nebo aplikaci, která využívá tento programovací jazyk. Jedná se o adresář, tedy místo v souborovém systému operačního systému, kde jsou uloženy soubory s příponou .js, případně modernější varianty jako .mjs nebo .cjs. Tyto soubory obsahují kód napsaný v jazyce JavaScript, který může sloužit k nejrůznějším účelům – od jednoduchých skriptů ovládajících chování webové stránky až po komplexní logiku rozsáhlých aplikací.

Každý zkušený vývojář dobře ví, že správná organizace těchto složek je naprosto zásadní pro udržitelnost a čitelnost projektu. Pokud jsou soubory JavaScriptu rozmístěny chaoticky bez jakékoliv struktury, stává se práce s projektem velmi obtížnou záležitostí, zvláště ve chvíli, kdy na něm pracuje více lidí najednou. Dobře navržená adresářová struktura umožňuje vývojářům rychle se orientovat v kódu, snadno nacházet konkrétní funkce nebo komponenty a efektivně spolupracovat v týmu.

V praxi se nejčastěji setkáváme s několika ustálenými přístupy k pojmenování a organizaci složek JavaScriptu. Složka pojmenovaná src nebo source bývá hlavním místem, kde sídlí veškerý zdrojový kód aplikace. Uvnitř této složky pak vývojáři zpravidla vytvářejí další podadresáře podle logického členění projektu. Může to být složka components pro znovupoužitelné součásti uživatelského rozhraní, složka utils pro pomocné funkce, složka services pro komunikaci s externími rozhraními nebo složka hooks v případě projektů využívajících framework React.

Soubory JavaScriptu uložené ve složkách mohou být vzájemně propojeny pomocí systému modulů. Moderní JavaScript podporuje nativní moduly prostřednictvím klíčových slov import a export, což umožňuje rozdělit kód do menších, logicky ucelených celků a ty pak podle potřeby importovat do jiných souborů. Tímto způsobem vzniká síť závislostí, která je přehledná a snadno udržovatelná.

Velkou roli při práci se složkami JavaScriptu hrají také nástroje jako webpack, Vite nebo Rollup, které slouží k tzv. bundlování – tedy ke slučování mnoha souborů z různých složek do výsledného balíčku, jenž je připraven pro nasazení v produkčním prostředí. Tyto nástroje dokáží sledovat závislosti mezi soubory, optimalizovat výsledný kód a výrazně zrychlit načítání webové aplikace v prohlížeči.

Nelze opomenout ani soubor package.json, který sice sám o sobě není souborem JavaScriptu v pravém slova smyslu, ale úzce s těmito složkami souvisí. Nachází se zpravidla v kořenovém adresáři projektu a definuje jeho základní vlastnosti, závislosti na externích knihovnách a skripty pro spouštění různých úloh. Právě díky tomuto souboru a správci balíčků jako npm nebo yarn lze snadno přidávat do projektu tisíce externích knihoven, jejichž soubory jsou pak ukládány do složky node_modules.

Správná práce se složkami JavaScriptu tedy není jen otázkou osobních preferencí vývojáře, ale přímo ovlivňuje kvalitu, výkon a dlouhodobou udržitelnost celého projektu. Čím lépe je adresářová struktura promyšlena od samého začátku, tím méně problémů vývojáři čelí v pozdějších fázích vývoje, kdy projekt roste a stává se složitějším.

Typická struktura adresáře JS projektu

Každý JavaScript projekt, ať už jde o jednoduchou webovou stránku nebo komplexní aplikaci postavenou na moderních frameworcích, má svou vlastní strukturu adresářů a souborů. Tato struktura není náhodná — vzniká na základě dlouholeté praxe vývojářů, kteří postupně přišli na to, jak nejlépe organizovat kód tak, aby byl přehledný, udržovatelný a snadno rozšiřitelný. Pochopení toho, jak taková struktura vypadá a proč je navržena právě tímto způsobem, je jedním ze základních předpokladů pro každého, kdo chce pracovat s JavaScriptem profesionálně.

Na samém vrcholu každého JS projektu se nachází takzvaný kořenový adresář, anglicky root directory. Právě zde najdeme soubory, které řídí celé chování projektu na té nejzákladnější úrovni. Patří sem například soubor package.json, který je v podstatě srdcem každého Node.js projektu. Tento soubor obsahuje metadata o projektu, seznam závislostí, skripty pro spouštění různých úloh a mnoho dalšího. Bez něj by správce balíčků npm nebo yarn vůbec nevěděl, jak s projektem pracovat.

Vedle package.json se v kořenovém adresáři typicky nachází také soubor .gitignore, který říká verzovacímu systému Git, které soubory a složky má ignorovat a nezahrnovat do repozitáře. Nejčastěji se sem uvádí složka node_modules, která může obsahovat tisíce souborů a jejíž přítomnost v repozitáři by byla zbytečná a kontraproduktivní. Dále tu bývá soubor .env pro ukládání citlivých proměnných prostředí, jako jsou přístupové klíče k API nebo databázová hesla.

Složka src, neboli source, je místem, kde se odehrává to nejdůležitější — samotný zdrojový kód aplikace. Právě sem vývojáři píší svůj JavaScript, organizují komponenty, definují logiku aplikace a strukturují vše tak, aby to dávalo smysl nejen jim samotným, ale i jejich kolegům. Uvnitř složky src se pak obvykle nachází další podadresáře. Například složka components obsahuje znovupoužitelné části uživatelského rozhraní, složka utils nebo helpers sdružuje pomocné funkce, které se používají napříč celou aplikací, a složka services zpravidla obsahuje kód zodpovědný za komunikaci s externími API nebo databázemi.

Dalším důležitým adresářem je složka public, která obsahuje statické soubory — tedy soubory, které se servírují přímo prohlížeči bez jakékoliv transformace. Najdeme zde typicky soubor index.html, různé obrázky, ikony nebo fonty. Tento adresář je v podstatě tím, co uživatel vidí jako výsledek celé aplikace.

Velmi důležitou roli hraje také složka node_modules. Tato složka vzniká automaticky při instalaci závislostí pomocí příkazu npm install nebo yarn install a obsahuje veškeré knihovny a balíčky, na kterých projekt závisí. Jak již bylo zmíněno, tato složka se do repozitáře nezahrnuje, protože ji lze kdykoliv znovu vygenerovat ze souboru package.json.

Pro projekty, které využívají testování — a každý seriózní projekt by ho využívat měl — existuje zpravidla složka tests nebo __tests__. Zde se nacházejí testovací soubory, které ověřují správnost chování jednotlivých funkcí a komponent. Moderní JavaScript ekosystém nabízí celou řadu testovacích frameworků, jako jsou Jest, Mocha nebo Vitest, a každý z nich má svá specifika, pokud jde o pojmenování a umístění testovacích souborů.

Konfigurace projektu je dalším tématem, které se přímo odráží ve struktuře adresářů. V kořenovém adresáři nebo ve speciální složce config se nacházejí různé konfigurační soubory — například webpack.config.js pro bundler Webpack, babel.config.js pro transpiler Babel nebo eslint.config.js pro nástroj ESLint, který hlídá kvalitu kódu. Tyto soubory jsou nezbytné pro správné fungování celého vývojového prostředí.

Je důležité si uvědomit, že neexistuje jedna univerzální struktura, která by vyhovovala všem projektům. Malý projekt s několika soubory bude mít přirozeně jednodušší organizaci než rozsáhlá enterprise aplikace s desítkami vývojářů. Nicméně základní principy zůstávají stejné — oddělení zdrojového kódu od konfigurace, logické seskupování souvisejících souborů a jasné pojmenování adresářů, které napovídá jejich obsah. Dodržování těchto principů výrazně usnadňuje orientaci v projektu a přispívá k jeho dlouhodobé udržovatelnosti.

Hlavní typy souborů uvnitř složky

Každý vývojář, který pracuje s JavaScriptem, se dříve nebo později setká s tím, že jeho projekt začne růst do takových rozměrů, kdy je nutné pečlivě přemýšlet o tom, jaké soubory vlastně uvnitř projektové složky najde a co každý z nich znamená. Složka JavaScriptového projektu totiž není jen hromada náhodně pojmenovaných souborů – je to promyšlená struktura, která odráží způsob, jakým celá aplikace funguje, jak se sestavuje a jak komunikuje s okolním světem.

Nejzákladnějším a zároveň nejdůležitějším souborem, který v téměř každé moderní JavaScriptové složce najdete, je soubor package.json. Tento soubor funguje jako srdce celého projektu. Obsahuje metadata o projektu, jako je jeho název, verze, autor a licence, ale především definuje závislosti – tedy balíčky a knihovny, na kterých projekt závisí. Bez tohoto souboru by správci balíčků jako npm nebo yarn vůbec nevěděli, co mají nainstalovat ani jak má projekt fungovat. Uvnitř package.json najdete také sekci scripts, kde jsou definovány příkazy pro spuštění, testování nebo sestavení aplikace.

Dalším velmi běžným souborem je soubor s příponou .js, tedy samotný JavaScriptový zdrojový kód. Tyto soubory mohou mít různé účely – některé definují komponenty, jiné obsahují pomocné funkce, další se starají o komunikaci s databází nebo externími API. V moderních projektech se stále častěji setkáte také s soubory s příponou .mjs, které označují ES moduly, nebo s příponou .cjs pro CommonJS moduly. Toto rozlišení je důležité zejména tehdy, když projekt kombinuje různé systémy pro správu modulů.

V projektech využívajících TypeScript, který je nadstavbou JavaScriptu, pak narazíte na soubory s příponou .ts nebo .tsx. Soubory .tsx jsou specifické pro projekty využívající React, kde TypeScript koexistuje s JSX syntaxí. Tyto soubory je nutné před spuštěním v prohlížeči nebo v prostředí Node.js nejprve zkompilovat do čistého JavaScriptu, k čemuž slouží TypeScriptový kompilátor nebo nástroje jako Babel.

Neméně důležitou roli hrají konfigurační soubory. Patří mezi ně například soubor .babelrc nebo babel.config.js, který říká Babelu, jak má transformovat moderní JavaScript do starší verze kompatibilní s různými prohlížeči. Podobně webpack.config.js definuje, jak má bundler Webpack sestavit výslednou aplikaci z mnoha zdrojových souborů do jednoho nebo několika výstupních souborů. V projektech využívajících Vite pak najdete soubor vite.config.js, který plní podobnou roli, ale s jiným přístupem k sestavování.

Zvláštní kategorií jsou soubory pro správu prostředí, nejčastěji pojmenované .env nebo .env.local. Tyto soubory obsahují proměnné prostředí, jako jsou přístupové klíče k API, adresy databází nebo jiné citlivé informace, které by neměly být součástí zdrojového kódu uloženého ve verzovacím systému. Proto je v každém dobře spravovaném projektu také soubor .gitignore, který verzovacímu systému Git říká, které soubory a složky má ignorovat a neukládat do repozitáře.

Testovací soubory tvoří další důležitou skupinu. Tyto soubory mají nejčastěji příponu .test.js nebo .spec.js a obsahují automatizované testy, které ověřují správnost chování kódu. Testovací frameworky jako Jest, Mocha nebo Vitest tyto soubory automaticky vyhledávají a spouštějí. Správně napsané testy jsou nesmírně cenné, protože umožňují vývojářům s jistotou provádět změny v kódu bez obavy, že něco rozbijí.

V projektech zaměřených na stylování a uživatelské rozhraní se v JavaScriptové složce mohou vyskytovat také soubory CSS, SCSS nebo LESS. Tyto soubory sice nejsou JavaScriptem v pravém slova smyslu, ale jsou součástí projektu a moderní bundlery je umí importovat přímo z JavaScriptových souborů a zpracovat je jako součást sestavovacího procesu.

Nesmíme zapomenout ani na soubor README.md, který je sice technicky dokumentačním souborem napsaným v Markdownu, ale v každém dobře vedeném projektu by neměl chybět. Obsahuje základní informace o projektu, návod na instalaci a spuštění a případně i přehled dostupných příkazů. Je to první věc, kterou vývojář přečte, když se s projektem setká poprvé.

Rozdíl mezi moduly a samostatnými skripty

V JavaScriptu existuje zásadní rozdíl mezi tím, jak fungují moduly a jak fungují samostatné skripty, a pochopení tohoto rozdílu je naprosto klíčové pro každého, kdo pracuje s organizací souborů v rámci složky nebo adresáře obsahujícího kód napsaný v JavaScriptu. Oba přístupy mají své místo, své výhody i svá omezení, a volba mezi nimi ovlivňuje celou architekturu projektu.

Samostatné skripty jsou historicky starší způsob, jak JavaScript fungoval od samého počátku. Když prohlížeč načte klasický skript pomocí tagu `