The Nebula File Size Monitor dashboard metabox periodically scans active theme files and lists them sorted by file size. Each group of file types (such as “Images”, “Styles”, or “Scripts”) has a file size budget which is compared to the actual file size. Files over the budget are bolded, and files twice the budget are highlighted in red.
Hovering over the file name will show the full path to the file. Files that can be viewed on the front-end (like images) will have an outbound link icon that can be clicked. Hovering over the size will show the percent of the budget that this file currently is.
Filters and Priority Groups
Developers can select different file groups based on category, but “Priority” groups are also provided which include:
- All Groups: This will show every file that Nebula is monitoring
- Largest Files (default): The largest 10 files in the file system
- Over Budget: All files that exceed their respective group’s file size budget.
- Approaching Budget: All files that are nearing the file size budget, but not over yet.
- Recently Modified: All files that have been modified recently either by a human or automated system.
- Security Concerns: Any file that exhibits some kind of suspicious trait when scanned.
When selecting a more specific file group, the budget percent column will be shown, along with the budgeted file size for that group underneath the table. From there, optimization tips can be toggled which will provide general recommendations for improving the file size of the selected file types.
Minor note: remember that when selecting the Recently Modified group, the sort is still by file size (not by modification date). The table will always be sorted by file size regardless of what filters are active.
The File Type select menu will provide a list of every file extension that was found in the scan, and further filter the currently selected group to specify those file types.
Tip: Use the “All Files” group when using the File Type dropdown filter in order to see all of the files of that extension. For reference, if viewing the Recently Modified group, when selecting a file extension it will only show files with that extension that have been recently modified.
Other File Attributes and Scanning
While scanning for file sizes, Nebula also checks some basic characteristics to denote other factors besides just size.
The result of some of the more notable traits will appear as icons next to the file name. These can include recently modified, “@todo” comments, “non-ASCII characters”, debug output, or security concerns, for example. Hovering over these icons will provide some context to what they indicate.
Note that to preserve memory, only the first few hundred kilobytes of each file are scanned. However, this should be plenty for the majority of files that need content scans.
Find Files Keyword Search
Other file attributes are scanned and added as hidden notes which can be searched with the “Find files” keyword search input. This keyword input will search any part of this table including file name, extension, group, size, icons, and hidden notes.
Here are some useful keywords to use to find other hidden traits of files:
empty-filedebug-outputstale-logtech-debtspace-indentationold-file- Also:
two-year-old-file,five-year-old-file, andten-year-old-file
- Also:
no-extensioncontains-lorem-ipsumaccessibility- Also:
a11y, orplaceholder-alt, ormissing-alt
- Also:
non-asciideprecated-function- Note that this does not check for all deprecated functions, only common/notable ones.
file-permissions- These are files with permissions set to “777” or “666”
remote-includeconcern-filenamesuspicious-string- You can also search for the suspicious strings themselves such as
base64_decode. Just remember that this is not searching the entire file contents in real-time; you are filtering by the flagged notes detected from the scan.
- You can also search for the suspicious strings themselves such as
last-modified-YYYY-MM-DD(where YYYY-MM-DD is replaced with the desired date)- Remember: partial searches work too, so to find all files last modified in 2025 you can search
2025-
- Remember: partial searches work too, so to find all files last modified in 2025 you can search
You can also search by file path (including partial paths) such as assets/images/meta.
Adding Files to be Monitored
By default, Nebula scans the entire child theme directory (or parent theme if no child theme is being used) as well as key log locations. However, additional files can be added to the monitor using provided hooks.
Adding Individual Files
add_filter('nebula_file_size_monitor', function($files_to_monitor){
$files_to_monitor[] = ABSPATH . 'wp-content/debug.log'; //Add the debug.log file from the wp-content directory
return $files_to_monitor;
});Adding Directories (Non-Recursively)
This will add all the files from within a directory, but will not add files within subdirectories within this directory.
add_filter('nebula_file_size_monitor', function($files_to_monitor){
$example_directory = ABSPATH . 'wp-content/plugins/nebula-docs/images/'; //The directory of files we want to add
$example_files = array_diff(scandir($example_directory), ['.', '..']); //Get all the actual files from the directory
foreach ( $example_files as $example_file ){
if ( is_file($example_directory . $example_file) ){ //Ignore directories themselves
$files_to_monitor[] = $example_directory . $example_file;
}
}
return $files_to_monitor;
});Adding Directories (Recursively)
This will add all files within a directory and also follow nested subdirectories and add those files as well. Also note in this example is another way of ignoring files. See further below for a way to ignore files more globally from the File Size Monitor.
add_filter('nebula_file_size_monitor', function($files_to_monitor){
$example_directory = ABSPATH . 'wp-content/plugins/nebula-docs/';
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($example_directory, FilesystemIterator::SKIP_DOTS)
);
foreach ( $iterator as $file ){
if ( $file->isFile() ){ //Ignore directories themselves
//Skip ignored files and directories
$ignored = array('.github', '.gitignore', '.git', 'screenshot.png', 'acf-json', 'img/meta');
foreach ( $ignored as $ignore ){
if ( str_contains($file->getPathname(), $ignore) ){
continue 2; //Skip this file
}
}
//Add to the file monitor
$files_to_monitor[] = $file->getPathname();
}
}
return $files_to_monitor;
});The Uploads Directory
If you were to add the entire /uploads/ directory to the monitor, it will likely quickly hit the file limit. Even if you were to increase the limit (see below), you would likely run into memory issues trying to scan the entire /uploads/ directory. If monitoring the /uploads/ directory is still desired, perhaps an alternative approach would be to scan only this years’ uploads?
add_filter('nebula_file_size_monitor', function($files_to_monitor){
$uploads_directory = ABSPATH . 'wp-content/uploads/' . date('Y') . '/';
if( is_dir($uploads_directory) ){
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($uploads_directory, FilesystemIterator::SKIP_DOTS)
);
foreach ( $iterator as $file ){
if ( $file->isFile() ){
$files_to_monitor[] = $file->getPathname();
}
}
}
return $files_to_monitor;
});Ignoring Files
Adding files or partial path matches here will ignore them entirely from the File Size Monitor. Files in the default scan directory, default log locations, and any added files/directories will be ignored if they match any of the ignored strings.
add_filter('nebula_file_size_monitor_ignored', function($ignored){
$ignored[] = 'images/meta';
$ignored[] = 'screenshot.png';
$ignored[] = 'readme';
return $ignored;
});Modifying/Adding File Groups
add_filter('nebula_file_size_monitor_groups', function($groups){
//Add a group
$groups['Maps'] = array(
'extensions' => array('map'), //Add as many relevant file extensions as needed here
'budget' => (KB_IN_BYTES*400),
'linkable' => true
);
//Change the file size budget of an existing group
$groups['Audio']['budget'] = MB_IN_BYTES*1.5;
return $groups;
});Changing the Default Selected File Group
You can change which file group is selected by default (or choose the All Files group) by using a filter such as the following. Please be careful when changing the default file group selection so that you do not lose sight of other large files!
add_filter('nebula_file_size_monitor_default_selection', function($default_selected_group){
return 'logs';
});Increasing the File Scan Limit
By default, the file scan is limited to optimize performance. This limit, however, can be changed with a filter. Nebula stores scan results in a transient so that this does not run every time the Dashboard is viewed, however it is still important to use caution when altering the file scan limit to avoid memory issues or long scan times.
add_filter('nebula_file_size_monitor_limit', function($limit){
return 3000; //Increase the file scan limit to 3,000 files
});Adding custom file checks
You can also add your own checks for the file scan. Useful to expand this tool to check for additional traits within each file’s content, path, or other property. The output strings from the $notes will be searchable via the “Find files” keyword input filter.
add_filter('nebula_file_size_monitor_notes', function($notes, $file_info){
if ( in_array($file_info['group'], array('Templating', 'Styles', 'Scripts')) ){ //Only check PHP, JS, and Sass/CSS (case sensitive)
$contents = file_get_contents($file_info['path'], false, null, 0, KB_IN_BYTES*300); //Only scan the first 300kb of the file (or choose your own limit)
$contents = strtolower($contents); //Lowercase the file contents
$custom_check_strings = array('hello', 'world'); //Example of a way to check for specific strings within the file
foreach ( $custom_check_strings as $custom_check_string ){
if ( str_contains($contents, $custom_check_string) ){
$notes[] = 'custom-check-string';
$notes[] = 'contains-' . $custom_check_string;
break; //Exit the foreach because we found one, or remove this to check for each individual entry
}
}
}
return $notes;
}, 10, 2);